前言#

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

Docker 构建教程#

拉取 Docker 库#

1
git clone -b master https://github.com/misskey-dev/misskey.git # 克隆Misskey仓库
2
cd misskey # 进入Misskey目录
3
git checkout master # 切换到master分支

配置文件设置#

复制配置文件示例#

使用以下命令复制配置文件的示例文件：

1
cp .config/docker_example.yml .config/default.yml # 复制Docker示例配置文件
2
cp .config/docker_example.env .config/docker.env # 复制Docker示例环境变量文件
3
cp ./compose_example.yml ./compose.yml # 复制Docker Compose示例文件

编辑配置文件#

编辑default.yml#

default.yml是Misskey的主要配置文件：

1
#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2
# Misskey configuration
3
#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
4

5
#   ┌─────┐
6
#───┘ URL └─────────────────────────────────────────────────────
7

8
# Final accessible URL seen by a user.
9
# You can set url from an environment variable instead.
10
url: https://example.tld/ # 你的实例域名
11

12
# ONCE YOU HAVE STARTED THE INSTANCE, DO NOT CHANGE THE
13
# URL SETTINGS AFTER THAT!
14

15
#   ┌───────────────────────┐
16
#───┘ Port and TLS settings └───────────────────────────────────
17

18
#
19
# Misskey requires a reverse proxy to support HTTPS connections.
20
#
21
#                 +----- https://example.tld/ ------------+
22
#   +------+      |+-------------+      +----------------+|
23
#   | User | ---> || Proxy (443) | ---> | Misskey (3000) ||
24
#   +------+      |+-------------+      +----------------+|
25
#                 +---------------------------------------+
26
#
27
#   You need to set up a reverse proxy. (e.g. nginx)
28
#   An encrypted connection with HTTPS is highly recommended
29
#   because tokens may be transferred in GET requests.
30

31
# The port that your Misskey server should listen on.
32
port: 3000 # 你的实例端口
33

34
#   ┌──────────────────────────┐
35
#───┘ PostgreSQL configuration └────────────────────────────────
36

37
db:
38
  host: db
39
  port: 5432
40

41
  # Database name
42
  # You can set db from an environment variable instead.
43
  db: misskey # 数据库名称
44

45
  # Auth
46
  # You can set user and pass from environment variables instead.
47
  user: example-misskey-user # 数据库用户名
48
  pass: example-misskey-pass # 数据库密码
49

50
  # Whether disable Caching queries
51
  #disableCache: true
52

53
  # Extra Connection options
54
  #extra:
55
  #  ssl: true
56

57
dbReplications: false # 是否启用数据库复制
58

59
# You can configure any number of replicas here
60
#dbSlaves:
61
#  -
62
#    host:
63
#    port:
64
#    db:
65
#    user:
66
#    pass:
67
#  -
68
#    host:
69
#    port:
70
#    db:
71
#    user:
72
#    pass:
73

74
#   ┌─────────────────────┐
75
#───┘ Redis configuration └─────────────────────────────────────
76

77
redis:
78
  host: redis # Redis 主机名
79
  port: 6379 # Redis 端口
80
  #family: 0  # 0=Both, 4=IPv4, 6=IPv6
81
  #pass: example-pass
82
  #prefix: example-prefix
83
  #db: 1
84

85
#redisForPubsub:
86
#  host: redis
87
#  port: 6379
88
#  #family: 0  # 0=Both, 4=IPv4, 6=IPv6
89
#  #pass: example-pass
90
#  #prefix: example-prefix
91
#  #db: 1
92

93
#redisForJobQueue:
94
#  host: redis
95
#  port: 6379
96
#  #family: 0  # 0=Both, 4=IPv4, 6=IPv6
97
#  #pass: example-pass
98
#  #prefix: example-prefix
99
#  #db: 1
100

101
#redisForTimelines:
102
#  host: redis
103
#  port: 6379
104
#  #family: 0  # 0=Both, 4=IPv4, 6=IPv6
105
#  #pass: example-pass
106
#  #prefix: example-prefix
107
#  #db: 1
108

109
#redisForReactions:
110
#  host: redis
111
#  port: 6379
112
#  #family: 0  # 0=Both, 4=IPv4, 6=IPv6
113
#  #pass: example-pass
114
#  #prefix: example-prefix
115
#  #db: 1
116

117
#   ┌───────────────────────────────┐
118
#───┘ Fulltext search configuration └─────────────────────────────
119

120
# These are the setting items for the full-text search provider.
121
fulltextSearch:
122
  # You can select the ID generation method.
123
  # - sqlLike (default)
124
  #   Use SQL-like search.
125
  #   This is a standard feature of PostgreSQL, so no special extensions are required.
126
  # - sqlPgroonga
127
  #   Use pgroonga.
128
  #   You need to install pgroonga and configure it as a PostgreSQL extension.
129
  #   In addition to the above, you need to create a pgroonga index on the text column of the note table.
130
  #   see: https://pgroonga.github.io/tutorial/
131
  # - meilisearch
132
  #   Use Meilisearch.
133
  #   You need to install Meilisearch and configure.
134
  provider: sqlLike # 全文搜索提供程序
135

136
# For Meilisearch settings.
137
# If you select "meilisearch" for "fulltextSearch.provider", it must be set.
138
# You can set scope to local (default value) or global
139
# (include notes from remote).
140

141
#meilisearch:
142
#  host: meilisearch
143
#  port: 7700
144
#  apiKey: ''
145
#  ssl: true
146
#  index: ''
147
#  scope: local
148

149
#   ┌───────────────┐
150
#───┘ ID generation └───────────────────────────────────────────
151

152
# You can select the ID generation method.
153
# You don't usually need to change this setting, but you can
154
# change it according to your preferences.
155

156
# Available methods:
157
# aid ... Short, Millisecond accuracy
158
# aidx ... Millisecond accuracy
159
# meid ... Similar to ObjectID, Millisecond accuracy
160
# ulid ... Millisecond accuracy
161
# objectid ... This is left for backward compatibility
162

163
# ONCE YOU HAVE STARTED THE INSTANCE, DO NOT CHANGE THE
164
# ID SETTINGS AFTER THAT!
165

166
id: 'aidx' # ID 生成方法
167

168
#   ┌────────────────┐
169
#───┘ Error tracking └──────────────────────────────────────────
170

171
# Sentry is available for error tracking.
172
# See the Sentry documentation for more details on options.
173

174
#sentryForBackend:
175
#  enableNodeProfiling: true
176
#  options:
177
#    dsn: 'https://[email protected]/0'
178

179
#sentryForFrontend:
180
#  vueIntegration:
181
#    tracingOptions:
182
#      trackComponents: true
183
#  browserTracingIntegration:
184
#  replayIntegration:
185
#  options:
186
#    dsn: 'https://[email protected]/0'
187

188
#   ┌─────────────────────┐
189
#───┘ Other configuration └─────────────────────────────────────
190

191
# Whether disable HSTS
192
#disableHsts: true
193

194
# Number of worker processes
195
#clusterLimit: 1
196

197
# Job concurrency per worker
198
# deliverJobConcurrency: 128
199
# inboxJobConcurrency: 16
200

201
# Job rate limiter
202
# deliverJobPerSec: 128
203
# inboxJobPerSec: 32
204

205
# Job attempts
206
# deliverJobMaxAttempts: 12
207
# inboxJobMaxAttempts: 8
208

209
# IP address family used for outgoing request (ipv4, ipv6 or dual)
210
#outgoingAddressFamily: ipv4
211

212
# Proxy for HTTP/HTTPS
213
#proxy: http://127.0.0.1:3128
214

215
proxyBypassHosts: # 代理绕过主机列表
216
  - api.deepl.com
217
  - api-free.deepl.com
218
  - www.recaptcha.net
219
  - hcaptcha.com
220
  - challenges.cloudflare.com
221

222
# Proxy for SMTP/SMTPS
223
#proxySmtp: http://127.0.0.1:3128   # use HTTP/1.1 CONNECT
224
#proxySmtp: socks4://127.0.0.1:1080 # use SOCKS4
225
#proxySmtp: socks5://127.0.0.1:1080 # use SOCKS5
226

227
# Media Proxy
228
#mediaProxy: https://example.com/proxy
229

230
# For security reasons, uploading attachments from the intranet is prohibited,
231
# but exceptions can be made from the following settings. Default value is "undefined".
232
# Read changelog to learn more (Improvements of 12.90.0 (2021/09/04)).
233
#allowedPrivateNetworks: [
234
#  '127.0.0.1/32'
235
#]
236

237
# Upload or download file size limits (bytes)
238
#maxFileSize: 262144000
239

240
# Log settings
241
# logging:
242
#   sql:
243
#     # Outputs query parameters during SQL execution to the log.
244
#     # default: false
245
#     enableQueryParamLogging: false
246
#     # Disable query truncation. If set to true, the full text of the query will be output to the log.
247
#     # default: false
248
#     disableQueryTruncation: false

请将url: https://example.tld/中的example.tld替换为你为Misskey实例分配的实际域名。
同时，db: misskey、user: example-misskey-user和pass: example-misskey-pass分别对应数据库名称、数据库用户名和数据库密码，请根据您的实际数据库配置进行修改，并确保这些凭据与环境变量的设置保持一致。

编辑docker.env#

docker.env文件包含了Docker容器运行所需的环境变量：

1
# misskey settings
2
# MISSKEY_URL=https://example.tld/
3

4
# db settings
5
POSTGRES_PASSWORD=example-misskey-pass # 数据库密码(如果修改了default.yml，这里也需要修改)
6
# DATABASE_PASSWORD=${POSTGRES_PASSWORD}
7
POSTGRES_USER=example-misskey-user # 数据库用户名(如果修改了default.yml，这里也需要修改)
8
# DATABASE_USER=${POSTGRES_USER}
9
POSTGRES_DB=misskey # 数据库名称(如果修改了default.yml，这里也需要修改)
10
# DATABASE_DB=${POSTGRES_DB}
11
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
sudo docker compose build # 构建Docker镜像
2
sudo docker compose run --rm web pnpm run init # 初始化数据库

启动Misskey实例#

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

1
sudo docker compose up -d # 启动Misskey容器

故障排除#

INTERNAL_ERROR错误处理#

如果访问Misskey实例时遇到以下错误：

1
Misskey Internal error occurred. Please contact us if the error persists.
2
INTERNAL_ERROR
3
5d37dbcb-891e-41ca-a3d6-e690c97775ac

这通常是由于文件权限问题引起的。请将/misskey/files目录权限设置为777：

1
sudo chmod -R 777 ./files # 设置files目录权限为777

设置完成后，重新启动Misskey容器

更新Misskey#

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

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

结语#

通过本教程，您已经成功学习了如何使用Docker部署和管理自己的Misskey实例。从环境准备、配置文件设置到实例的启动和更新，我们一步步完成了整个部署过程。