Misskey 微博

关于Misskey

Misskey 是一个开源分布式微博平台项目。开发始于2014年，由syuilo在日本开发。它具有丰富的功能，如驱动器和反应，以及高度可自定义的 UI。

历史

在开发之初，公告板是主要服务，但随着用户发布短文并添加按时间顺序流动的时间线功能，它越来越受欢迎，并且开发逐渐成为主要服务。它最初不是分布式的，但在 2018 年，ActivityPub 实现了分布式，成为更受人们认可和使用的服务，并一直持续到今天。

我与Misskey的历程

其实我接触misskey也没多久，可以说是相爱相杀，毕竟咱喜欢搞新奇的东西，搭建这个东西也经历了波波折折

体验站

我的 Misskey 实例已经重新上线啦，欢迎来玩：点我前往（屑殇小窝，Misskey v2026.7.0，注册开放，需要邮箱验证）

搭建教程

准备工作

一个域名，并解析到你的服务器。分布式联邦靠域名识别实例，上线后域名不能改，想好再动手
一台 Linux 服务器（Ubuntu/Debian 最佳），建议 2C4G 起步，内存不足时构建阶段会很难受（见 FAQ 的 swap 方案）
两种部署方式二选一：
- Docker Compose：官方推荐，环境隔离、升级简单，下面方式一
- 手动编译：不依赖 Docker、便于定制，需要自己装 Node.js/PostgreSQL/Redis，下面方式二

方式一：Docker Compose 部署（推荐）

克隆与配置

git clone -b master https://github.com/misskey-dev/misskey.git
cd misskey
cp .config/docker_example.yml .config/default.yml
cp .config/docker_example.env .config/docker.env
cp ./compose_example.yml ./compose.yml

编辑 .config/default.yml：

# 最终访问地址，必须改成你的域名（上线后不能改！）
url: https://你的域名/
# 监听端口，反代指向这里
port: 3000
# db 和 redis 保持 host 为 db / redis（compose 服务名）
db:
  host: db
  port: 5432
  db: misskey
  user: example-misskey-user
  pass: example-misskey-pass
redis:
  host: redis
  port: 6379

编辑 .config/docker.env，把示例密码改成强密码，数据库连接会通过 DATABASE_URL 注入：

1
2
3

POSTGRES_PASSWORD=换成你的强密码
POSTGRES_USER=misskey
POSTGRES_DB=misskey

构建、初始化、启动

1
2
3

sudo docker compose build          # 首次构建比较久
sudo docker compose run --rm web pnpm run init   # 初始化数据库
sudo docker compose up -d

浏览器访问 http://服务器IP:3000 看到 Misskey 页面就成功了（下一步配 HTTPS 反代）。

方式二：手动编译部署

安装依赖

1
2
3

# Ubuntu/Debian
sudo apt update
sudo apt install -y build-essential git ffmpeg postgresql postgresql-contrib redis-server

Node.js 要求 v22.15.0+（v22 系列）或 v24.10.0+（v24 系列），推荐用 nvm 安装：

1
2
3

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22

pnpm 要求 v10.16.0+，用 corepack 启用：

1 2	corepack enable corepack prepare pnpm@latest --activate

为 PostgreSQL 创建数据库和用户：

1	sudo -u postgres psql

1 2	CREATE USER misskey WITH PASSWORD '你的强密码'; CREATE DATABASE misskey OWNER misskey;

安装 Misskey

Misskey 不允许 root 直接运行，创建独立用户：

sudo adduser --disabled-password --disabled-login misskey
sudo -iu misskey
git clone --recursive https://github.com/misskey-dev/misskey.git
cd misskey
git checkout master
git submodule update --init
NODE_ENV=production pnpm install --frozen-lockfile

配置与初始化

1 2	cp .config/example.yml .config/default.yml nano .config/default.yml

url: https://你的域名/   # 上线后不能改！
port: 3000
db:
  host: localhost
  port: 5432
  db: misskey
  user: misskey
  pass: 你的强密码
redis:
  host: localhost
  port: 6379
# 初始设置密码：部署完成后打开站点用它创建管理员账号
setupPassword: 用openssl rand -base64 32 生成一串

构建并初始化数据库（首次构建较久）：

1 2	NODE_ENV=production pnpm run build pnpm run init

启动验证：

1	NODE_ENV=production pnpm run start

systemd 托管

Ctrl+C 停掉前台进程，创建服务文件让 Misskey 开机自启、崩溃自动重启：

[Unit]
Description=Misskey daemon

[Service]
Type=simple
User=misskey
ExecStart=/usr/bin/npm start
WorkingDirectory=/home/misskey/misskey
Environment="NODE_ENV=production"
TimeoutSec=60
StandardOutput=journal
StandardError=journal
SyslogIdentifier=misskey
Restart=always

[Install]
WantedBy=multi-user.target

1
2
3

sudo systemctl daemon-reload
sudo systemctl enable --now misskey
systemctl status misskey

反向代理与 HTTPS（必做）

Misskey 页面和实时时间线依赖 WebSocket，反代必须支持 Upgrade 头，否则会出现”能打开页面但发帖不刷新”的怪问题。官方只建议反代 443 → 3000，不要在 Misskey 前面再叠一层反代。

Nginx

server {
    listen 80;
    server_name msk.example.com;
    # 媒体上传，默认限制 256M 以内足够
    client_max_body_size 256m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_redirect off;
    }
}

用 certbot 一键签发 HTTPS 证书：

1 2	sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d msk.example.com

Caddy（更省事）

Caddy 自动申请并续期证书，配置只有一行：

1
2
3

msk.example.com {
    reverse_proxy 127.0.0.1:3000
}

如果反代和 Misskey 之间有 CDN（如 Cloudflare），需要在 default.yml 里配置 trustProxy 信任 CDN 回源 IP，否则限流会把反代 IP 当成用户 IP。

初始设置与日常管理

创建管理员：配置里设置了 setupPassword 的话，打开站点会引导你进入初始设置，输入该密码即可创建管理员账号。没有设置的话第一个注册的用户会成为管理员
站点信息：管理员登录后在「控制台」里改站点名、描述、图标、主题色等

注册与邮箱：控制台可开启注册审核、邮箱验证；要发验证邮件必须在 default.yml 配 SMTP：

smtp:
  host: smtp.example.com
  port: 465
  user: your@mail.com
  pass: your-password
  secure: true
  from: your@mail.com

对象存储：默认媒体存在本地 files 目录，媒体量大之后建议接 S3 兼容存储（Cloudflare R2、Backblaze B2 等），控制台里直接配置

更新与备份

更新

升级前先看 CHANGELOG 有没有额外步骤，然后：

# Docker 方式
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

# 手动方式
git checkout master
git pull
git submodule update --init
NODE_ENV=production pnpm install --frozen-lockfile
NODE_ENV=production pnpm run build
pnpm run migrate
sudo systemctl restart misskey

升级失败时可以试试 pnpm run clean（或 pnpm run clean-all）和 pnpm rebuild 再重新构建。

备份

Misskey 的数据 = PostgreSQL 数据库 + 媒体文件目录，两个都要备份：

# 数据库（压缩导出）
pg_dump -U misskey -Fc misskey | gzip > misskey-$(date +%Y%m%d-%H%M).dump.gz
# 媒体文件（默认目录）
tar -czf files-$(date +%Y%m%d-%H%M).tar.gz files

Docker 方式在容器里执行：

1	sudo docker compose exec db pg_dump -U misskey -Fc misskey \| gzip > misskey-$(date +%Y%m%d-%H%M).dump.gz

建议用 cron 每天自动备份并同步到其他机器（异地备份防丢站）。

常见问题 FAQ

构建或迁移时内存不足（OOM / killed）
加 swap：

1 2	sudo fallocate -l 4G /swapfile && sudo chmod 600 /swapfile sudo mkswap /swapfile && sudo swapon /swapfile

页面能打开，但发帖/时间线不实时刷新
反代没有配置 WebSocket Upgrade 头，对照上文 Nginx/Caddy 配置检查
注册时验证邮件收不到
SMTP 配置错误，或者云服务器厂商封了 25 端口（国内厂商默认封），改用 465/587 端口
域名能改吗
不能。上线联邦后改 url 会导致签名失效、联邦数据错乱，只能换新域名重新开始
为什么显示用户来源 IP 不对 / 莫名被限流
反代或 CDN 后面需要配置 trustProxy
升级后 500 错误
先看日志，试试 pnpm run clean + 重新构建；Docker 方式重新 docker compose build 后再 up -d

如果上面的问题没能解决你的问题，欢迎在评论区留言提问。