一、速览：Mastodon 解决了什么问题

入门

你可能有过这种经历：辛辛苦苦积累的账号和内容，某天因为平台规则变动一夜清零。Mastodon 把社交网络的控制权交还给你——它是一套可以自己架在服务器上的微博程序，数据存在你自己的数据库里。

更特别的是，每个 Mastodon 服务器都是一个独立"小区"，但小区之间可以互相走动：你在自家服务器发的帖子，别人在别的服务器（甚至别的软件）上照样能看到、能回复。这个互联互通的大网络叫联邦宇宙（Fediverse）。

本文的目标很具体：从一台空白 Linux 服务器开始，用 Docker 部署出一个能注册、能发帖、能关注其他服务器用户的 Mastodon 实例。

二、动手前的准备

入门

Mastodon 比一般的小工具"重"一些，它需要跑 Web 服务、后台任务、图片处理、数据库等好几个组件，所以对机器有最低要求。

硬件建议：至少 2 核 CPU、2GB 内存、40GB 硬盘。内存低于 2GB 时，部署过程中的依赖编译很容易失败，不建议硬撑。

软件要求：一台能联网的 Linux 服务器（Ubuntu 22.04 / Debian 12 均可），以及一个已经解析到这台服务器的域名，比如 social.example.com。

为什么必须要域名？因为联邦宇宙里其他服务器要通过域名找到你，这是 ActivityPub（一套规定"社交软件之间怎么互相打招呼"的国际标准协议）的硬性要求。没有域名，你的实例会像没有门牌号的房子，别人寄不了信。

还需要准备：一台能 SSH 登录服务器的电脑，以及下面这些会被 Docker 镜像自动装好的组件（知道名字即可）：

• Ruby on Rails：程序主体
• PostgreSQL 14+：存用户、帖子等结构化数据的数据库
• Redis 7.0+：当"临时中转站"，负责消息推送和缓存
• Node.js 24+、FFmpeg 5.1+：分别负责前端资源打包和视频处理

三、快速部署：Docker Compose 一键起服务

入门

这里要用到 Docker——一种把软件连同它需要的环境一起打包成"集装箱"的工具，你不用挨个装 Ruby、PostgreSQL，只要运行集装箱就行。docker compose 则是一份"装箱清单"，一次启动多个集装箱并让它们互相连通。

第 1 步：装 Docker

curl -fsSL https://get.docker.com | sh

第 2 步：拉取代码并准备配置文件

git clone https://github.com/mastodon/mastodon.git
cd mastodon
cp .env.production.sample .env.production

.env.production 是整套服务的总开关面板，后面第四节会逐项解释。

第 3 步：生成前端资源

docker compose run --rm web bundle exec rake mastodon:generate_pack
docker compose run --rm web bundle exec rake mastodon:push

第一条把网页界面的 CSS 和 JS 打包好，第二条生成服务密钥。这两步跑完才算把"箱子"封好。

第 4 步：填配置

用编辑器打开 .env.production，至少改这几项：

LOCAL_DOMAIN=social.example.com
DB_PASS=some-strong-password
SECRET_KEY_BASE=          # 留空，下一步自动生成
OTP_SECRET=               # 留空，下一步自动生成

LOCAL_DOMAIN 换成你自己的域名；DB_PASS 是数据库密码，随便敲一串足够长的字符。

接着让 Mastodon 自己补上密钥：

docker compose run --rm web rake mastodon:generate_secret

它会输出两个值，把 SECRET_KEY_BASE 和 OTP_SECRET 填进去即可。

第 5 步：建库并启动

docker compose run --rm web rake db:create
docker compose run --rm web rake db:migrate
docker compose up -d

第 6 步：创建管理员账号

docker compose run --rm web rake mastodon:create_owner

按提示输入邮箱、用户名和密码，第一个账号就是实例管理员。

部署完成后，浏览器访问 https://social.example.com 看到注册页，才算真正成功。如果暂时只有 IP 没有域名，Web 界面能打开，但联邦功能会受限，建议先配置域名再投入使用。

四、配置详解：看懂 .env.production

进阶 · 推荐细读

`文件里变量很多，下面挑新手必须搞懂的几组讲清楚。

域名相关

数据库与缓存

用官方 compose 部署时，这些默认指向容器内部，不用改。

端口

Mastodon 由多个容器组成，各自占不同端口：Web 界面默认 3000，流式推送（让别人的时间线实时刷新）默认 4000。docker compose 已经在本机内部把它们接好了，你只需要确保对外暴露的 80 和 443 端口没被占用，因为浏览器和别的服务器都从这两个口进来。

存储路径

用户上传的图片和视频存放在 ./public/system 目录里。这是整套部署中最重要的一份数据，它不随容器销毁，但会随着实例变大而急剧膨胀，运维时要定期备份和清理。

建议：配置文件改完后，用 docker compose restart 让改动生效；改数据库相关变量则需要重新跑一次 db:migrate。

五、功能导览：装好之后能干什么

入门

发帖：登录后顶部输入框就是时间线，可以发文字、链接、图片和视频。支持"仅关注者可见""指定人可见"等可见范围，也支持内容敏感警告（点一下才展开）。

关注与联邦：在搜索框输入 @用户名@其他站点域名 就能关注别的服务器上的人。你的主页地址形如 @你@social.example.com，把这个告诉别人，他们也能反过来关注你。

过滤与屏蔽：设置里可以配置屏蔽词、静音、拉黑；账号还能"锁定"，关注需要你批准。这套机制配合实例管理员的举报处理流程，构成 Mastodon 的日常治理方式。

管理面板：管理员账号登录后访问 /admin，可以处理举报、管理用户权限、查看实例运行状态。实例规则、简介等信息也在后台设置。

第三方客户端：Mastodon 本身就是 OAuth2 授权服务（一种"允许第三方 App 代替你登录"的标准），手机端可以使用 Tusky、Ice Cubes 等应用，比网页端更省流量。

六、常见问题

进阶 · 推荐细读

端口被占用：docker compose up 报 80 端口错误，通常是系统自带的 Apache/Nginx 挡了路。可以先停掉它们：

sudo systemctl stop apache2 nginx

容器起不来，日志里全是内存不足：Mastodon 编译依赖时吃内存较多。2GB 机器建议临时加 2GB 交换空间再部署，而不是强行重试。

数据库连接失败：确认 .env.production 里 DB_PASS 与首次启动时设置的一致；如果中途改过，需要 docker compose down 后重新 db:create。

别人搜不到我的用户：多半是 LOCAL_DOMAIN 与实际域名不符，或者 80/443 没有正确转发到容器。用在线联邦测试工具检查你的域名是否能被正常发现。

上传失败：检查 ./public/system 目录权限，以及服务器磁盘剩余空间。图片和视频占用增长比想象中快。

七、运维进阶：让实例长期稳定跑下去

深入 · 老手可选

反向代理与 HTTPS：联邦宇宙强制要求 HTTPS（加密连接），否则其他服务器会拒绝与你通信。推荐用 Caddy 做反向代理，它能自动申请并续期证书，只需在 Caddyfile 里写一条转发规则指向本机 3000 端口即可。用 Nginx 也行，但证书需要用 Certbot 手动维护。

定时任务：Mastodon 有一批需要定期执行的清理任务，务必在宿主机加一条 crontab，用 docker compose run --rm web rake mastodon:media:clear 和 rake mastodon:accounts:clear 等命令定时跑，否则媒体文件会无限堆积。

升级流程：

docker compose pull
docker compose run --rm web rake db:migrate
docker compose up -d

升级前建议先备份数据库和 public/system 目录，Major 版本升级务必先看官方变更说明。

数据备份：把 PostgreSQL 用 pg_dump 导出成 SQL 文件，加上 public/system 目录一起打包，异地保存。恢复时按相反顺序导入即可。

最后一点建议：运营一个实例意味着要承担内容治理责任，包括处理举报、遵守当地法规。如果只是想先体验，从单人小圈子起步、逐步开放注册，是压力最小的方式。

项目信息

参考链接

• GitHub 仓库
• 项目主页

延伸阅读

想继续探索？这些同领域的教程可能也适合你：

• 「beszel」中文使用教程
• 「caddy」中文使用教程
• 「ServerStatus-Hotaru」中文使用教程