【实用的开源工具】Misskey：自己域名下的联邦微博

「实用的开源工具」系列：我只收集值得用的开源项目，写清楚它能做什么、怎么部署、有哪些坑，并在文末标明出处。内容整理自官方文档，核对日期 2026-10-31，具体版本以官方为准。文中的命令和配置都来自官方 Hub 文档和官方仓库，我没有在自己的机器上逐条跑过，强烈建议先用一个测试域名走一遍，再上正式域名，原因见下面的第一条提醒。

项目信息卡

项目	说明
名称	Misskey
做什么	开源的、支持联邦的社交媒体平台（微博形式），通过 ActivityPub 与其他服务器互通
许可证	AGPL-3.0
仓库	github.com/misskey-dev/misskey
官方文档	misskey-hub.net
最近版本	2026.10.1（2026-10-23 发布，查询于 2026-10-31），仓库未归档，最近推送为 2026-10-31
运行方式	Docker Compose：Misskey 主程序（从源码构建镜像）、PostgreSQL、Redis
默认端口	主程序监听 3000，官方要求前面放反向代理提供 HTTPS
最重要的一条	域名一旦开始使用就不能改，也不要用同一个域名重建数据库（官方在多个页面用 Danger 提示）

它能做什么

微博式的时间线：发帖（官方称 Note）、关注、回应（Reaction）、投票、话题标签、MFM 排版语法等。
联邦：默认通过 ActivityPub 与其他服务器互通，你的用户可以关注别的服务器上的人，反过来也一样。官方也支持限制联邦或完全关闭。
自定义表情、网盘（Drive）、Deck 多栏界面、主题、插件、Webhook 等，这些在官方的用户文档里都有专门页面。
角色（Roles）：给用户授权、限额、做权限分级，可以手动或按条件自动分配。
举报与管理：管理员能收到用户和其他服务器的举报，在控制面板里处理。

适合：想要一个有自己域名的小型社交站，自己人或小圈子用。不适合：想“随便试试、过几天换域名”的人（见下文）。

先想清楚：域名定了就不能改

官方多个页面都放了同一条 Danger 提示：服务器开始使用以后，不要用这个域名/主机名重建数据库。配置文件示例里也写着：

url 这一项：“一旦启动实例，之后不要再改 URL 设置”。
id 这一项（ID 生成方式，默认 aidx）：同样是启动后不要改。

为什么重要，我的理解（通用的联邦原理，不是官方原话）：别的服务器是按你的域名来认你的用户和帖子的，一旦你换了域名或者清空数据库再用回原域名，已经联邦出去的内容和关系会对不上。所以：

先在测试域名上走通整个流程，确认没问题后，用正式域名全新安装。
正式域名用熟悉的主域名或子域名，想清楚，之后不要再换。
不要用“删掉重装”的方式来修问题。

另外，官方的“重要注意事项”页面还提醒了几件与联邦相关的事：帖子发出去后不能保证在其他所有服务器上都被删除；私密性在其他服务器上也没有保证；Drive 里的文件只要知道网址谁都能访问；用户名注册后不能再改，账号删除后同一用户名也无法再拿回来。

部署（官方 Docker Compose 指南）

官方 Docker 指南的前提是已装好 Docker 和 Docker Compose。流程是：克隆仓库、复制三个示例配置、改配置、构建并初始化数据库、启动。

1. 克隆仓库

bash

git clone -b master https://github.com/misskey-dev/misskey.git
cd misskey
git checkout master

官方文档跟踪 master 分支。如果想固定到某个发布版本，可以改为检出发布标签，例如 git checkout 2026.10.1（这是我的建议，不是文档里的写法；标签名请先用 git tag 确认存在，并看发布说明）。

2. 复制示例配置

bash

cp .config/docker_example.yml .config/default.yml
cp .config/docker_example.env .config/docker.env
cp ./compose_example.yml ./compose.yml

官方说明：按说明编辑 default.yml 和 docker.env，compose.yml 也按需修改（比如要改端口）。

3. 编辑 `.config/default.yml`

示例文件里的关键项如下（只列最重要的，其余请直接看示例文件里的注释）：

yaml

# 用户最终访问到的完整网址。启动之后不要再改！
url: https://example.com/

# Misskey 监听的端口
port: 3000

db:
  host: db
  port: 5432
  db: misskey
  user: example-misskey-user
  pass: example-misskey-pass

redis:
  host: redis
  port: 6379

说明：

url：写你对外的 HTTPS 地址（示例文件里是 https://example.tld/，这里用 example.com 代替）。
db 下面的 host: db、redis 下面的 host: redis：就是 Compose 里的服务名，用示例里的默认值即可。
db.user、db.pass 必须改成自己的，并且要和 .config/docker.env 里的数据库账号密码一致（这是我的提示，两个文件是分开写的）。
id: 'aidx' 保持默认，启动后不要改。
fulltextSearch.provider 默认是 sqlLike，不需要额外组件；示例里也写了 sqlPgroonga 和 meilisearch 的选项，需要再装别的组件，这篇不展开。
maxFileSize（字节）默认被注释掉，示例里的值是 262144000（约 250MB）。

初始设置密码 setupPassword：仓库的 .config/example.yml（手动安装用）里有这一项，说明是“用于启动管理员账号设置的密码，初始设置完成后不再使用”，并写明“通过互联网安装时务必修改”：

yaml

setupPassword: 换成一个随机的长密码

（示例文件里这行是被注释掉的，要启用就去掉开头的 #。）

注意：Docker 用的 docker_example.yml 里没有这一项，我也没在官方 Docker 指南里看到专门说明。因为两者读取的是同一套配置机制，我推断可以直接把这行加进 default.yml，但这是推断，请以你装的版本为准。不设置的话，向导里这一栏留空就可以继续（见下文），也就是说谁先打开网址谁就能创建管理员，所以安装完要立刻去创建账号，别让服务公网裸奔。

4. 编辑 `.config/docker.env`

示例文件里是这样的：

env

POSTGRES_PASSWORD=example-misskey-pass
POSTGRES_USER=example-misskey-user
POSTGRES_DB=misskey
DATABASE_URL="postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}"

把用户名和密码换成你自己的，并和 default.yml 保持一致。

5. 编辑 `compose.yml`

示例 Compose 的结构（节选）：

yaml

services:
  web:
    build: .
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - ./files:/misskey/files
      - ./.config:/misskey/.config:ro

  redis:
    image: redis:7-alpine
    volumes:
      - ./redis:/data

  db:
    image: postgres:18-alpine
    env_file:
      - .config/docker.env
    volumes:
      - ./db:/var/lib/postgresql

要点：

官方 Compose 里的服务是 web、redis、db。db 和 redis 在 internal_network（internal: true）里，不对外；web 同时在内部和外部网络。
web 默认写的是 "3000:3000"，对所有网卡开放。前面有 Nginx 的话，我建议改成只绑本机：

yaml

    ports:
      - "127.0.0.1:3000:3000"

这是我的调整，不是官方默认值。

文件里还有被注释掉的 mcaptcha（自托管验证码）和 meilisearch（全文搜索）两个可选服务，需要的话取消注释并按注释配置，这篇不展开。
数据目录都在项目目录下：./db（数据库）、./redis、./files（上传的文件）、./.config（配置，以只读方式挂入容器）。

6. 构建、初始化、启动

按官方文档：

bash

sudo docker compose build
sudo docker compose run --rm web pnpm run init
sudo docker compose up -d

官方说明构建需要一些时间。关于内存：官方的手动安装和 Ubuntu 指南写明构建和数据库迁移至少需要 2GB 内存，内存不够就加 swap，或者在别处构建。这是对源码构建的要求，Docker 构建也是从源码构建镜像，所以小内存的机器要留意（这是我的推断）。

反向代理（Nginx）

官方配置里写得很清楚：Misskey 需要反向代理提供 HTTPS，并且 HTTPS 连接“强烈建议”，因为令牌可能出现在 GET 请求里。官方 Hub 提供了一份 Nginx 示例，下面是核心部分（域名请换成自己的；完整版还包括缓存相关配置和 TLS 参数，请看官方页面）：

nginx

# WebSocket 用
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    location / { return 301 https://$server_name$request_uri; }
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    # 改成你需要的上传大小上限
    client_max_body_size 80m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_redirect off;

        # 如果前面还有别的反向代理或 CDN，官方说明要删掉下面这几行（X-* 三行）
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        # WebSocket 用
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

官方还说明：如果前面是 Cloudflare 这类 CDN，要删掉示例里标注的那几行转发头；配置完执行 sudo nginx -t 检查，再重启 Nginx。

第一次使用：初始化向导

官方 Hub 的 Docker 指南没有写第一次打开网页后的步骤（这是一处文档空白）。下面是我从仓库里的前端源码和英文界面文案整理的，界面文字以你的版本为准：

全新安装后第一次访问你的网址，会看到“Welcome to Misskey!”，提示安装已经完成，并要求先创建管理员账号。
页面里有一栏“Initial password for setup”。界面的提示是：自己安装的就填配置文件里设的密码；用托管服务的用现成给的；没设置过就留空继续。
然后填用户名和密码，创建管理员。
之后进入“服务器设置”向导，问你几个问题，界面写明这里的设置事后都可以改，也可以跳过：

- 怎么使用：单人服务器、小组服务器（邀请你信任的人）、公开服务器（任何人都能注册）。 - 预期用户规模：100 以下、100 到 1000、1000 以上。选大规模时会提示可能需要负载均衡、数据库复制等进阶设施。 - 是否连接到联邦宇宙（Fediverse）：连上之后可以和其他服务器交换内容；更细的联邦设置事后再配。 - 是否自动清理收到的远程内容：联邦会持续流入内容，开启后会清理过期且没有被引用的内容来省空间。 - 管理员信息：用于接收咨询的联系方式，界面注明开启公开服务或联邦时必须填写。

向导最后给出推荐设置，点“应用”即可。

联邦的设置

官方有一页介绍联邦模式（该页在 Hub 的英文站点上仍是日文，后面提到的举报页也一样，下面是我的翻译）：Misskey 默认就开启 ActivityPub 联邦，一般不需要额外设置。可以在控制面板的“全般”里改，有三档：

全部：和所有服务器联邦（被你屏蔽的除外），默认值。
指定主机：只和白名单里的服务器联邦。
无：不与任何其他服务器联邦。

审核、防骚扰和防垃圾内容

这里只写官方文档和界面里明确提到的内容：

举报：用户和其他服务器都可以提交举报，会出现在控制面板的“举报”里。官方建议经常查看。处理完要标记为“解决”，并区分“解决（认可）”（举报属实，采取了措施）和“解决（否认）”（举报不成立，未做处理）。对远程用户的举报可以转发给对方服务器，转发时举报人会显示为匿名的系统账号 @instance.actor，你收到的来自别的服务器的举报也可能是这个账号。
举报通知：可以在控制面板的举报页面里设置 Webhook 或邮件通知。
管理备注：可以给举报写只有管理员和审核员能看到的备注。
角色与权限：角色的基础权限分为普通用户、审核员（Moderator，可做基础审核操作）、管理员（Administrator，可改所有设置）。更细的限制通过“策略（Policy）”设置，比如网盘容量、能否发公开帖子等。
公开注册要小心：初始化向导里选“公开服务器”时，界面会提醒：接收大量陌生用户有风险，建议配备可靠的审核机制；并提醒为了避免服务器成为垃圾信息的跳板，应该同时启用 reCAPTCHA 之类的防机器人功能。仓库的配置示例里的 proxyBypassHosts 列表也能看到 reCAPTCHA、hCaptcha 和 Cloudflare 的验证域名，说明这几种验证服务是受支持的（具体怎么配请看控制面板里的安全设置，文档没有专门的步骤）。
关闭本地/社交/全局时间线：官方“审核技巧”页说明，LTL/STL/GTL 可以分别在控制面板里关闭。它们让新用户容易发现别人，但也意味着不当内容更容易被看到；关闭前要先向用户说明理由。管理员和审核员关闭后依然能看到这些时间线。
限制联邦范围：见上一节，白名单模式是最保守的做法。

官方文档没有写的部分：具体怎么封禁某个远程服务器、怎么批量处理垃圾账号，我没有查到对应的 Hub 页面，这篇不写。

备份

官方 Docker 指南没有写备份。下面是通用做法，不是官方文档：

要备份的东西：.config/（配置）、./files（用户上传文件）、数据库。./redis 也在项目目录，但一般只是缓存和队列。
数据库可以用 pg_dump 导出，例如：

bash

docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > misskey-$(date +%F).sql

这条命令里的环境变量来自 db 容器自己的环境（Compose 里通过 env_file 传给了它）。也可以停机后整体复制 ./db 目录。

更新与卸载

更新：官方 Docker 指南的做法如下。官方特别提醒：更新前一定要先看发布说明，确认有没有额外步骤（通常没有）。

bash

git stash
git checkout master
git pull
git submodule update --init
git stash pop
sudo docker compose build
sudo docker compose stop && sudo docker compose up -d

官方说明耗时取决于更新内容和数据库大小。官方安装脚本页的 FAQ 提到：Docker 下 Misskey 启动时会跑数据库迁移，所以更新后短时间内可能暂时 502，等迁移结束再看。更新前先备份（通用建议）。

执行 CLI 管理命令的写法是：

bash

sudo docker compose run --rm web node packages/backend/built/tools/foo bar

其中 foo bar 是占位，具体工具见官方的“管理命令”页面。

卸载（通用的 Docker 操作，不是官方文档）：docker compose down 停止并删除容器；数据都在项目目录下的 db、files 等目录里，不删这些目录数据就在。请记住前面的提醒：同一个域名不要再用全新的数据库来用。

踩坑清单

域名（url）启动后不能改，也不要用同一域名重建数据库。 官方在 Docker、手动、安装脚本等每一页都有 Danger 提示。
id 生成方式也不能改。 default.yml 里 id: 'aidx' 的注释明确要求启动之后不要改。
一定要有 HTTPS 的反向代理。 配置里写明 Misskey 本身不处理 HTTPS，官方强烈建议加密连接，因为令牌可能出现在 GET 请求里。
数据库账号密码要在两个文件里保持一致。 一个是 .config/default.yml 的 db.user、db.pass，一个是 .config/docker.env 的 POSTGRES_USER、POSTGRES_PASSWORD（连接串 DATABASE_URL 也依赖它们）。这是我的提示，官方只说“按说明编辑”。
示例里的账号密码是公开的。 示例文件里的 example-misskey-user 和 example-misskey-pass 是占位，必须改掉。
通过互联网安装时要设置 setupPassword。 官方示例文件明确写“务必修改”；不设置则向导里留空即可继续，意味着谁先访问谁就能建管理员（后半句是我的推论）。装完立刻建账号。
更新前先看发布说明。 官方 Docker 指南的 Warning。
构建至少 2GB 内存。 来自官方手动安装/Ubuntu 指南。内存不够会构建失败，可以加 swap 或在别处构建。
上传大小有两道关。 Nginx 示例里是 client_max_body_size 80m，而 Misskey 的 maxFileSize 示例值是约 250MB。想传大文件，两处要一起改（这是我的提示）。
设置了 proxy（出站代理）就要自己管内网访问限制。 官方在配置注释里强调：配置了代理后，Misskey 不再检查出站请求的目标是不是内网或回环地址，必须在代理上禁止访问内网和云元数据地址（如 169.254.169.254）；proxyBypassHosts 里也只能放你信任的主机。
改源码要公开。 Misskey 是 AGPL-3.0。官方 Hub 提醒：修改过源码（包括 fork）就必须公开改动，配置文件里给了具体选项；原样运行则不需要做任何事。
公开注册风险大。 向导和官方文案都建议配备审核机制，并启用防机器人功能。
联邦内容会持续占用存储。 向导里有“自动清理收到的远程内容”选项，官方说明是为了节省存储；小服务器建议了解后再决定。
用户名不能改。 官方“重要注意事项”：注册后不可修改，删除账号后也拿不回同名用户名。
Docker 发布的端口会绕过 ufw 之类的防火墙。 这是通用的 Docker 行为，所以示例里把 3000 绑到了 127.0.0.1。

【实用的开源工具】Misskey：自己域名下的联邦微博

项目信息卡

它能做什么

先想清楚：域名定了就不能改

部署（官方 Docker Compose 指南）

1. 克隆仓库

2. 复制示例配置

3. 编辑 .config/default.yml

4. 编辑 .config/docker.env

5. 编辑 compose.yml

6. 构建、初始化、启动

反向代理（Nginx）

第一次使用：初始化向导

联邦的设置

审核、防骚扰和防垃圾内容

备份

更新与卸载

踩坑清单

出处

相关文章

3. 编辑 `.config/default.yml`

4. 编辑 `.config/docker.env`

5. 编辑 `compose.yml`