前言#

Misskey 是一个开源的、去中心化的社交网络平台，它提供了丰富的功能和高度的自定义性，让用户能够自由地构建和管理自己的社交空间。与传统社交媒体不同，Misskey 支持联邦宇宙（Fediverse）协议，允许不同实例之间的用户相互交流，同时保持数据的控制权和隐私性。

开始部署你的 Misskey 实例#

拉取代码#

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

复制配置文件示例#

1
cp .config/docker_example.yml .config/default.yml
2
cp .config/docker_example.env .config/docker.env
3
cp ./compose_example.yml ./compose.yml

编辑 default.yml#

default.yml 是 Misskey 的核心配置文件。以下列出需要关注的关键配置项：

1
url: https://example.tld/       # 必改：替换为你的实际域名
2

3
port: 3000                      # Misskey 监听端口，通常无需修改
4

5
db:
6
  host: db                     # 数据库主机名
7
  port: 5432                   # 数据库端口号
8
  db: misskey                   # 数据库名称
9
  user: example-misskey-user    # 数据库用户名
10
  pass: example-misskey-pass    # 数据库密码
11

12
dbReplications: false # 数据库复制，建议关闭
13

14
redis:
15
  host: redis                     # Redis 主机名
16
  port: 6379                      # Redis 端口号
17

18
id: 'aidx'                      # ID 生成方式，启动后请勿更改
19

20
fulltextSearch:
21
  provider: sqlLike             # 全文搜索，可选 sqlLike / sqlPgroonga / meilisearch
22

23
proxyBypassHosts: # 反向代理绕过主机名，用于访问外部服务
24
  - api.deepl.com               # DeepL API 主机名
25
  - api-free.deepl.com         # DeepL API 主机名，用于免费翻译
26
  - www.recaptcha.net          # reCAPTCHA 主机名，用于验证码
27
  - hcaptcha.com               # hCaptcha 主机名，用于验证码
28
  - challenges.cloudflare.com # Cloudflare 主机名，用于验证码

注意事项：

url 和 id 这两项一旦启动实例后不可更改，请务必在首次启动前确认正确。

更多可选配置（如 Sentry 错误追踪、Meilisearch、Redis 分离等）可参考 Misskey 官方文档，此处不一一展开。

编辑 docker.env#

docker.env 包含 PostgreSQL 的连接凭据，必须与 default.yml 中的 db 配置保持一致：

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

如果修改了 default.yml 中的数据库用户名、密码或数据库名，请同步修改此处，否则 Misskey 将无法连接数据库。

编辑compose.yml#

compose.yml文件定义了 Docker 容器的配置：

1
services:
2
  web:
3
    build: .
4
    restart: always
5
    links:
6
      - db
7
      - redis
8
#     - mcaptcha
9
#     - meilisearch
10
    depends_on:
11
      db:
12
        condition: service_healthy
13
      redis:
14
        condition: service_healthy
15
    ports:
16
      - "3000:3000" # 映射主机端口到容器端口
17
    networks:
18
      - internal_network
19
      - external_network
20
    # env_file:
21
    #   - .config/docker.env
22
    volumes:
23
      - ./files:/misskey/files
24
      - ./.config:/misskey/.config:ro
25

26
  redis:
27
    restart: always
28
    image: redis:7-alpine
29
    networks:
30
      - internal_network
31
    volumes:
32
      - ./redis:/data
33
    healthcheck:
34
      test: "redis-cli ping"
35
      interval: 5s
36
      retries: 20
37

38
  db:
39
    restart: always
40
    image: postgres:18-alpine
41
    networks:
42
      - internal_network
43
    env_file:
44
      - .config/docker.env
45
    volumes:
46
      - ./db:/var/lib/postgresql
47
    healthcheck:
48
      test: "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"
49
      interval: 5s
50
      retries: 20
51

52
#  mcaptcha:
53
#    restart: always
54
#    image: mcaptcha/mcaptcha:latest
55
#    networks:
56
#      internal_network:
57
#      external_network:
58
#        aliases:
59
#          - localhost
60
#    ports:
61
#      - 7493:7493
62
#    env_file:
63
#      - .config/docker.env
64
#    environment:
65
#      PORT: 7493
66
#      MCAPTCHA_redis_URL: "redis://mcaptcha_redis/"
67
#    depends_on:
68
#      db:
69
#        condition: service_healthy
70
#      mcaptcha_redis:
71
#        condition: service_healthy
72
#
73
#  mcaptcha_redis:
74
#    image: mcaptcha/cache:latest
75
#    networks:
76
#      - internal_network
77
#    healthcheck:
78
#      test: "redis-cli ping"
79
#      interval: 5s
80
#      retries: 20
81

82
#  meilisearch:
83
#    restart: always
84
#    image: getmeili/meilisearch:v1.3.4
85
#    environment:
86
#      - MEILI_NO_ANALYTICS=true
87
#      - MEILI_ENV=production
88
#    env_file:
89
#      - .config/meilisearch.env
90
#    networks:
91
#      - internal_network
92
#    volumes:
93
#      - ./meili_data:/meili_data
94

95
networks:
96
  internal_network:
97
    internal: true
98
  external_network:

构建镜像与初始化数据库#

使用以下命令进行Misskey的构建和数据库初始化。这可能需要一些时间。

1
docker compose build                # 构建 Docker 镜像（首次较慢）
2
docker compose run --rm web pnpm run init  # 初始化数据库

启动Misskey实例#

完成构建和初始化后，使用以下命令启动Misskey容器：

1
docker compose up -d

故障排除#

INTERNAL_ERROR错误处理#

访问实例时出现 Misskey Internal error occurred，通常是文件权限问题：

1
chmod -R 777 ./files
2
docker compose restart web

更新Misskey#

当有新版本发布时，可以使用以下步骤更新Misskey实例：

1
git stash # 保存当前工作目录的更改
2
git checkout master # 切换到master分支
3
git pull # 拉取最新代码
4
git submodule update --init # 更新子模块
5
git stash pop # 恢复之前的更改
6
docker compose build # 构建新镜像
7
docker compose stop && docker compose up -d # 重启容器