Misskey 2026.10.1 配置参数详解

目标：把 Misskey 2026.10.1 的配置文件 .config/default.yml 从头到尾逐项讲清——每个参数的含义、默认值、改动影响，并给出「改配置 → 重启 → 观测生效」的实测证据链。全部参数口径来自官方 .config/docker_example.yml 模板注释、产物内 packages/backend/built/config.js 源码核对与 2026-11-02 实测回显。部署过程见 《Misskey 2026.10.1 Docker Compose 部署指南》，命令行工具见 《Misskey 2026.10.1 常用 CLI 命令与工具详解》。

一、环境信息

• 组件与版本：Misskey 2026.10.1（预构建产物 misskey/misskey:2026.10.1，实测启动日志 Misskey v2026.10.1）。
• 配置载体：部署目录 .config/default.yml（Docker 路线模板）+ .config/docker.env（环境变量），只读挂载进容器 /misskey/.config。
• 验证载体：产物内编译产物 built/.config.json、REST API POST /api/meta、容器日志、PostgreSQL 18.6 / Redis 7.4.12 直查。
• 生效手段：本文所有参数改动均通过 docker compose restart web 重启验证（回显见第十二章）。

二、配置体系：三层文件与加载顺序

2.1 三层结构

Misskey 的配置不是「读 YAML 直接用」，而是三层流水线：

产物启动命令 pnpm run migrateandstart 的第一步就是编译（实测回显）：

$ node ./scripts/compile_config.js
/misskey/.config/default.yml → /misskey/built/.config.json
Configuration compiled ✓

编译脚本源码（产物内 scripts/compile_config.js，实测核对）写明设计意图："YAMLファイルをJSONファイルに変換するスクリプト / ビルド前に実行し、ランタイムにjs-yamlを含まないようにする"（转 JSON 后运行时不再携带 YAML 解析器）。

2.2 文件选择与 env 兜底

compile_config.js 的输入文件选择逻辑（实测源码）：

• MISSKEY_CONFIG_YML 环境变量指定时 → 编译 .config/<该值>；
• 否则 NODE_ENV=test → test.yml，其余 → default.yml。

loadConfig()（产物内 built/config.js 实测核对）的 env 兜底清单：

优先级：YAML 显式值 > env 兜底 > 代码默认值（代码默认值见各章标注，来源 loadConfig() 的 ?? 合并）。

2.3 编译产物实例

实测 built/.config.json 头部（本文部署的最终状态，密钥为演示口令）：

{"_NOTE_":"This file is auto-generated from YAML file. DO NOT EDIT.","url":"http://127.0.0.1:8138/","port":3000,"db":{"host":"db","port":5432,"db":"misskey","user":"misskey","pass":"q1w2e3r4"},"dbReplications":false,"redis":{"host":"redis","port":6379},"fulltextSearch":{"provider":"sqlLike"},"id":"aidx","clusterLimit":2,"proxyBypassHosts":["api.deepl.com","api-free.deepl.com","www.recaptcha.net","hcaptcha.com","challenges.cloudflare.com"],"maxFileSize":104857600,"logging":{"level":"info","access":{"statusClasses":["4xx","5xx"]}}}

_NOTE_ 字段是编译脚本注入的警告——不要手工编辑该 JSON，改 default.yml 后重启即可。

💡 技术拓展：社交服务端的配置形态不止「文件编译」一种。常见对比——

形态	代表	取舍
文件 + 启动时编译快照（本文）	Misskey	运行时零解析开销；改配置必须重启生效
文件直接解析	多数 Go/Rust 服务	无中间层，但每次启动重解析
文件 + 数据库双层可热改	Akkoma/Pleroma（configurable_from_database）、Mastodon setting_overrides	管理面板可改；文件与库状态易失配
纯环境变量	云原生十二要素	简单项适用，复杂结构表达力差

Misskey 选第一种：实例级参数全部走文件，管理面板改的是「实例设置」数据库项，与本文文件参数是两条正交通道。

三、URL 与监听参数

url: http://127.0.0.1:8138/
port: 3000

• url：实例对外 URL，派生出 host/hostname/scheme/wsUrl/apiUrl/authUrl/driveUrl 等全部运行时地址（loadConfig() 实测），并写进联邦对象签名与 ActivityPub URI。模板原文两次警告：启动后不可更改。官方安装文档另有同口径警告："Do not recreate the database with the domain/hostname of the server once you have started using it!"
• port：监听端口，容器内固定 3000，宿主映射由编排决定（实测 8138:3000）。
• socket / chmodSocket：以 Unix socket 代替 TCP 监听的两项（默认注释），env 兜底 PORT 仅对 TCP 有效。
• trustProxy：反向代理信任网段，代码默认值（实测 config.js）：10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、127.0.0.1/32、::1/128、fc00::/7——落在默认私有网段内的反代无需显式配置即可正确还原客户端 IP。
• enableIpRateLimit：按 IP 限流总闸，代码默认 true（第十二章登录 429 的源头开关）。
• disableHsts：关闭 HSTS 头（默认启用）。

⚠️ 要点：url 与编排端口必须口径一致——本文 url 写 http://127.0.0.1:8138/（宿主映射地址），容器内监听 3000；若上生产 HTTPS，改 url 为 https://域名/ 并在前置 nginx/caddy 终结 TLS，模板 ASCII 图明确「Misskey requires a reverse proxy to support HTTPS」。

四、PostgreSQL 参数

db:
  host: db
  port: 5432
  db: misskey
  user: misskey
  pass: q1w2e3r4

dbReplications: false

• db.host/port：编排服务名 db + 5432；
• db.db/user/pass：必须与 docker.env 的 POSTGRES_DB/USER/PASSWORD 一致（实测均 misskey/misskey/q1w2e3r4）；留空则回退 DATABASE_* env；
• db.disableCache：关闭查询缓存（默认注释=启用）；
• db.extra：透传 pg 连接选项（如 ssl: true），跨机部署数据库时在此加 TLS；
• dbReplications + dbSlaves：读写分离开关与只读副本清单（默认注释），开启后联邦收件等负载可分流。

生效验证（实测直查）：

docker exec misskey-db psql -U misskey -d misskey -tAc "select version();"

PostgreSQL 18.6 on x86_64-pc-linux-musl, compiled by gcc (Alpine 15.2.0) 15.2.0, 64-bit

五、Redis 参数

redis:
  host: redis
  port: 6379

• redis.host/port：编排服务名 redis；可选 pass（口令）、prefix、db（库号，默认 0）、family（0=双栈/4/6）；
• prefix 的实测形态：convertRedisOptions 把 prefix 默认值设为实例 host，键前缀 keyPrefix = "<prefix>:"——实测 Redis 键全部形如 127.0.0.1:8138:queue:...，多实例共用一套 Redis 时靠它隔离（改 prefix 等于换命名空间，旧键即孤儿）。

5.1 按用途拆分实例

模板提供四个可选段（默认全部注释），把不同负载拆到独立 Redis：

未配置的用途自动回退主 redis（loadConfig() 实测：redisForPubsub: config.redisForPubsub ? ... : redis）。

💡 技术拓展：队列/缓存后端选型对比——

方案	代表	特点
单 Redis 实例承载全部（本文）	Misskey 默认	部署最简，中小实例够用
按用途拆多 Redis 实例	Misskey redisFor*	隔离爆炸半径（队列积压不拖垮推送）
Redis Cluster	Misskey 不支持声明式接入	需自行以代理模式呈现单端点
内嵌/无队列	Akkoma（BEAM 内建）	少一个依赖，少一层伸缩手段

本文实测单实例承载（redis_mode:standalone，DBSIZE 首启 59 键，含 queue:*、list:userTimeline:*、limit:ip-*:signin:min 混合键空间）。

六、全文搜索与 ID 生成

fulltextSearch:
  provider: sqlLike
id: 'aidx'

• fulltextSearch.provider 三选一：sqlLike（默认，PostgreSQL 标准 LIKE，零扩展）、sqlPgroonga（需装 pgroonga 扩展并手工建索引）、meilisearch（需独立服务 + meilisearch: 段配 host/apiKey/scope）。实测启动日志实录：[SearchService] -- Provider: sqlLike；
• id：对象 ID 生成方式，可选 aid/aidx/meid/ulid/objectid，启动后不可更改（模板原文 DO NOT CHANGE）。实测 aidx 产物：用户 at2j3aq0wb6e0003、贴文 at2kj3wqcfdt0003（20 位、毫秒级有序）。

七、进程与作业队列参数

clusterLimit: 2

• clusterLimit：worker 进程数，代码默认 undefined（单 worker，模板注释示例 #clusterLimit: 1）。Node cluster 模型：master 拉起 N 个 worker，每个 worker 同时处理 HTTP 与消费队列；经验取「CPU 核数」。第十二章实测改 2 生效；
• threadPoolSize：CPU 密集任务额外线程池（每 worker），代码默认 1；
• 作业并发/限速/重试（模板注释示例，均按 worker 维度生效）：

• 缓存上限类（代码默认值实测）：perChannelMaxNoteCacheCount 默认 1000、perUserNotificationsMaxCount 默认 500、deactivateAntennaThreshold 默认 7 天（毫秒）。

八、出站网络与安全参数

• proxy / proxySmtp：HTTP(S) 与 SMTP 出站代理。模板用大段 IMPORTANT 注释警告：配置代理后 Misskey 不再自检目标是否为内网地址（SSRF 防护完全委托给代理），必须让代理拒绝 RFC1918/回环/链路本地/云元数据地址；
• proxyBypassHosts：直连白名单（模板默认含 DeepL 与验证码域名，实测保留原值）——白名单内主机绕过代理直连，同样可能跳过私有地址检查，只列可信域名；
• allowedPrivateNetworks：内网附件上传例外清单（默认注释=禁止），如 127.0.0.1/32；
• outgoingAddress / outgoingAddressFamily：出站绑定地址/协议族（ipv4/ipv6/dual），多出口 IP 场景用；
• mediaProxy：外部媒体代理服务地址；未配置时实测走内置代理（/api/meta 回显 "mediaProxy":"http://127.0.0.1:8138/proxy"，externalMediaProxyEnabled=false）；
• videoThumbnailGenerator：外部视频缩略图服务（默认注释，内置 ffmpeg 兜底——产物安装了 ffmpeg，实测 Dockerfile）。

九、上传限制参数

maxFileSize: 104857600

• maxFileSize：上传统一下限（字节），代码默认 262144000（250MiB），模板注释示例同值；本文实测改 104857600（100MiB）。该值直接出现在 POST /api/meta 回显（第十二章生效实证），前端上传组件按它做客户端预检；
• 相关但不在本文件的：云盘容量/单类型白名单等属「实例设置」数据库项（实测 /api/meta 的 policies.driveCapacityMb:100、uploadableFileTypes），在管理面板改，不走 default.yml。

十、日志参数

logging:
  level: info
  access:
    statusClasses:
      - '4xx'
      - '5xx'

模板注释给出的完整结构（实测核对）：

⚠️ 要点：access 日志默认零输出（statusClasses 未配置），排障时临时加 ['4xx','5xx'] 是最小代价的观测手段——第十二章实测 404/405/429 全部现形。

十一、错误追踪与其他参数

• sentryForBackend / sentryForFrontend：Sentry 双端接入（默认注释）。模板注释含 2026-10 版细节：disabledIntegrations 按集成名关闭自动埋点（示例 ['Postgres']）；dataCollection 整体替换 Misskey 的默认脱敏集（默认不采用户信息/cookie/URL query/HTTP body/DB 参数）；默认阻止 sentry-trace/baggage 头外发到联邦远端，tracePropagationTargets 仅列内部服务；
• setupPassword：为初始化引导通道（部署篇第十一章 /api/admin/accounts/create）附加口令（默认无）；
• publishTarballInsteadOfProvideRepositoryUrl：源码分发方式开关（默认 false，/api/meta 实测回显 repositoryUrl 指向 GitHub）；
• pidFile：PID 文件路径（类型上必填项；实测模板未设、产物内无 pid 文件残留，容器场景基本用不到）；
• disableHsts：见第三章。

十二、参数生效实测验证（改后重启全链路）

本章在部署篇的实例上连续验证三组参数。统一生效手段：

docker compose restart web

实测回显：

 Container misskey-web Restarting 
 Container misskey-web Started 

重启日志首尾（实测，节选）：

query: SELECT * FROM "migrations" "migrations" ORDER BY "id" DESC
No migrations are pending
INFO *	[core boot]	Misskey v2026.10.1
INFO *	[core boot]	Starting 2 workers...
DONE *	[core boot]	Now listening on port 3000 on http://127.0.0.1:8138

No migrations are pending 同时证明：改配置重启不会触碰数据库，迁移只在有增量时执行。

12.1 clusterLimit：1 → 2

首启日志（clusterLimit 注释状态，单 worker）：

INFO *	[core boot]	Starting 1 worker...
INFO 1	[core]	Start worker process... pid: 212

在 default.yml 写入 clusterLimit: 2 并重启后（实测日志）：

INFO *	[core boot]	Starting 2 workers...
INFO 1	[core]	Start worker process... pid: 212
INFO 2	[core]	Start worker process... pid: 213

worker 进程数与配置一致（日志实录两个 worker pid 212/213），验证通过——master + N worker 的 cluster 形态由日志的 Starting N workers... 与逐 worker 的 Start worker process... pid: 行直接可观测。

12.2 maxFileSize：250MiB → 100MiB

改 default.yml 为 maxFileSize: 104857600 重启后，两层观测：

第 2 层编译产物（docker exec misskey-web cat built/.config.json 节选）：

"maxFileSize":104857600

第 3 层 API 出口（POST /api/meta 节选）：

{"version": "2026.10.1", "uri": "http://127.0.0.1:8138", "maxFileSize": 104857600, "maxNoteTextLength": 3000, "disableRegistration": true}

配置 → 编译 → API 全链路生效，验证通过。

12.3 logging.access.statusClasses：打开 4xx/5xx

模板默认无 logging: 段（access 零输出）。写入 ['4xx','5xx'] 重启后，用三类错误请求打日志（实测 access 行）：

WARN *	[access]	POST - 404 0.61ms 85B
WARN *	[access]	GET /api/meta 405 0.31ms 0B
WARN *	[access]	POST /api/signin-flow 429 1.46ms 163B

分别对应：旧登录端点 /api/signin（已移除→404）、GET /api/meta（Misskey API 一律 POST→405）、登录限流触发（→429）。验证通过，且每条带耗时与响应字节，可直接当轻量访问日志用。

12.4 数据存活复核

三组改动全部重启后：

docker exec misskey-db psql -U misskey -d misskey -tAc "select count(*) from note;"

2

贴文计数与重启前一致——配置变更对业务数据零影响。

十三、常见坑小结

十四、小结与关联

Misskey 2026.10.1 的文件配置面收敛在「一个 YAML + 一次重启」：三层流水线（YAML→编译 JSON→运行时对象）让参数校验前移到启动期，env 兜底照顾容器化最小写面；真正需要敬畏的是 url/id 两个一次定型项，以及「文件参数」与「管理面板实例设置」两条正交通道的边界（前者管连接与进程，后者管业务策略）。

• 部署全过程：《Misskey 2026.10.1 Docker Compose 部署指南》
• 选型与架构背景：《Misskey 2026.10.1 介绍与选型指南》
• CLI 与运维命令：《Misskey 2026.10.1 常用 CLI 命令与工具详解》

参考链接

• 官方配置模板：https://github.com/misskey-dev/misskey/blob/master/.config/docker_example.yml（本文参数口径的注释来源）
• 配置加载源码：产物内 packages/backend/built/config.js（仓库 packages/backend/src/config.ts）
• 编译脚本：产物内 scripts/compile_config.js、ormconfig.js
• 官方管理文档：https://misskey-hub.net/docs/for-admin/
• Meilisearch：https://www.meilisearch.com/；pgroonga：https://pgroonga.github.io/
• Sentry Node SDK：https://docs.sentry.io/platforms/node/