Akkoma 3.20.1 配置参数详解

目标：把 Akkoma 3.20.1 的配置体系讲透——配置文件如何分层、instance gen 生成的每一项参数是什么意思、改了如何生效。全部参数解说基于 2026-11-02 实测部署实例的真实配置文件（config/prod.secret.exs）、仓库默认配置（config/config.exs）与 API 实测回显，不是文档转抄。部署过程见 《Akkoma 3.20.1 Docker Compose 部署指南》，配置迁移命令的完整 CLI 语境见 《Akkoma 3.20.1 常用 CLI 命令与工具详解》。

一、环境信息

• 组件与版本：Akkoma 3.20.1（stable 分支 bc62dd80，运行时自报 3.20.1-0-gbc62dd8），Elixir 1.15.4 / OTP 26 / PostgreSQL 14.24。
• 取证实例：本地实测实例「Akkoma Test」，Web 入口 127.0.0.1:8129，配置文件为部署篇第九章 mix pleroma.instance gen 生成、按官方流程改名而来的 config/prod.secret.exs（实测 2615 字节）。
• 参照文件：仓库默认配置 config/config.exs（27453 字节）与参数说明书 config/description.exs（106305 字节，机器可读的全量参数描述，管理端 UI 与 mix pleroma.docs 都从它生成）。

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

2.1 文件角色

Elixir 按 MIX_ENV=prod 编译 release 时读取 config/prod.secret.exs，其键值逐项覆盖 config.exs 的默认值；没写的键保持默认。因此实例配置只需写「与默认不同」的部分——实测 prod.secret.exs 全文只有 80 余行。

2.2 实测实例的完整 prod.secret.exs（密钥已截断）

import Config

config :pleroma, Pleroma.Web.Endpoint,
   url: [host: "localhost", scheme: "https", port: 8129],
   http: [ip: {0, 0, 0, 0}, port: 4000],
   secret_key_base: "UtdpSo+7fTs81usHeTZfR7fI3aFwdpGbqegyhh2x2P5gIAzXVpuCrn0hD/3JhaU9",
   live_view: [signing_salt: "D92Lp4MJ"],
   signing_salt: "9Apvw9TC"

config :pleroma, :instance,
  name: "Akkoma Test",
  email: "root@localhost",
  notify_email: "root@localhost",
  limit: 5000,
  registrations_open: true

config :pleroma, :media_proxy,
  enabled: false,
  redirect_on_failure: true

config :pleroma, Pleroma.Repo,
  adapter: Ecto.Adapters.Postgres,
  username: "akkoma",
  password: "akkoma",
  database: "akkoma",
  hostname: "db"

config :web_push_encryption, :vapid_details,
  subject: "mailto:root@localhost",
  public_key: "BJKHWBRTLqfAFZSJnM64pnMLNkIKyLlaxTnGhOyjmOO6YpmDnZqdW77xTEvQb7EeYnYzOOei19QBGU8XMTG9gxQ",
  private_key: "wlp1HvL5Wx7Z7So3z82THRLQv70KzgEy3Vw39TOvacE"

config :pleroma, :database, rum_enabled: false
config :pleroma, :instance, static_dir: "/opt/akkoma/static"
config :pleroma, Pleroma.Uploaders.Local, uploads: "/opt/akkoma/uploads"

config :joken, default_signer: "8DxYWUOeRED1PHeigVzCJHy25iV1DEHnNnxMBwjRRuhQEzPg20Qmm8KkWNfqOe0J"

config :pleroma, configurable_from_database: false

config :pleroma, Pleroma.Upload,
  filters: [Pleroma.Upload.Filter.Exiftool.ReadDescription, Pleroma.Upload.Filter.Exiftool.StripMetadata],
  base_url: ""

config :pleroma, :instance,
  description: "Akkoma 测试实例：quzuo.net 配置实测"

最后一段是部署完成后手工追加的实例描述修改（见第十章生效验证）。以下章节逐项解说。

三、Endpoint 与网络参数（config :pleroma, Pleroma.Web.Endpoint）

server: Cowboy 响应头（实测 curl -sI 回显节选）证明 HTTP 层由 Cowboy 直接承载，无 nginx 依赖：

HTTP/1.1 200 OK
access-control-allow-credentials: true
access-control-allow-origin: *
cache-control: max-age=0, private, must-revalidate
content-security-policy: upgrade-insecure-requests;style-src 'self' 'nonce-0mTOjrzCzBmbML-';font-src 'self';script-src 'self' 'nonce-0mTOjrzCzBmbML-';connect-src 'self' https://localhost:8129 wss://localhost:8129;media-src 'self' https:;img-src 'self' data: blob: https:;default-src 'none';base-uri 'none';frame-ancestors 'none';manifest-src 'self';
server: Cowboy
x-frame-options: DENY
x-request-id: GOQaX40jZi8FzC4AAAJF

CSP/x-frame-options/referrer-policy 等安全头由 config :pleroma, :http 与 Phoenix 默认中间件产生，connect-src 里的 wss://localhost:8129 即 url 参数联动——改 url 后 WebSocket 地址自动跟随。

四、:instance 参数组（实例门面）

实测生成值与仓库默认值对照（默认值摘自 config/config.exs L197 起）：

五、数据库参数

config :pleroma, Pleroma.Repo,
  adapter: Ecto.Adapters.Postgres,
  username: "akkoma",
  password: "akkoma",
  database: "akkoma",
  hostname: "db"

hostname: "db" 是编排内部服务名解析（部署篇第四章），暴露到公网前应与数据库口令一起改掉。config :pleroma, :database, rum_enabled: false 对应 instance gen 的 --rum N 选项：RUM 索引加速高频搜索但增大写入开销，中小实例保持 false。

3.20.1 无 Redis 参数可配：对源码全文检索 redis 零命中，任务队列由 Oban（PostgreSQL 内建）承担，缓存由应用内 Cachex 承担。

六、上传与媒体参数

config :pleroma, Pleroma.Upload,
  filters: [Pleroma.Upload.Filter.Exiftool.ReadDescription, Pleroma.Upload.Filter.Exiftool.StripMetadata],
  base_url: ""
config :pleroma, Pleroma.Uploaders.Local, uploads: "/opt/akkoma/uploads"

• uploader 默认 Pleroma.Uploaders.Local（未写即默认），文件落 uploads 目录；换 S3 时按 prod.secret.exs 里预留的注释块改 Pleroma.Uploaders.S3 + config :ex_aws, :s3 凭证。
• filters 两项对应 instance gen 的 --strip-uploads-metadata Y（ExifTool 剥离 EXIF）与 --read-uploads-description Y（读图片描述作为 alt text），依赖构建时安装的 exiftool。
• base_url: "" 留空 = 媒体走本站路径；S3/CDN 部署才填公网前缀。
• media_proxy 实测被 instance gen 设为 enabled: false（默认配置里是 enabled），即远程图片直连原站加载；redirect_on_failure: true 表示代理失败时 302 到原地址。

七、前端参数（config :pleroma, :frontends）

config.exs L743-806 的默认结构（实测摘录）：

config :pleroma, :frontends,
  primary: %{"name" => "pleroma-fe", "ref" => "stable"},
  admin: %{"name" => "admin-fe", "ref" => "stable"},
  mastodon: %{"name" => "mastodon-fe", "ref" => "akkoma"},
  pickable: [
    "pleroma-fe/stable"
  ],
  swagger: %{
    "name" => "swagger-ui",
    "ref" => "stable",
    "enabled" => false
  },
  available: %{
    "pleroma-fe" => %{
      "name" => "pleroma-fe",
      "blind_trust" => true,
      "git" => "https://akkoma.dev/AkkomaGang/akkoma-fe",
      "bugtracker" => "https://akkoma.dev/AkkomaGang/akkoma-fe/issues",
      "build_url" =>
        "https://akkoma-updates.s3-website.fr-par.scw.cloud/frontend/${ref}/akkoma-fe.zip",
      "ref" => "stable",
      "build_dir" => "dist"
    },
    ...
  }

解说：

• primary：/web 主界面用哪个前端；admin：/pleroma/admin 管理端；mastodon：Mastodon 风格前端（不能设为 primary，注释原文 "Mastodon-Fe cannot be set as a primary"）。
• pickable：允许用户在设置里自助切换的前端白名单。
• swagger.enabled：默认 false，打开后提供 OpenAPI 交互文档。
• available：已知前端的下载元数据，build_url 模板中 ${ref} 被替换为版本号；安装名用 available 的键（mastodon-fe），用仓库名 masto-fe 会触发 "without a bugtracker; refusing install"（部署篇排障 #5）。
• 安装落盘路径固定为 static/frontends/<name>/<ref>，实测目录树：

static/frontends/:
admin-fe
mastodon-fe
pleroma-fe

八、密钥与安全参数

九、文件配置与数据库配置的双轨机制

Akkoma 的配置可以在「文件」与「数据库」间迁移，由 mix pleroma.config 子命令族操作（完整实测见 CLI 篇）：

# 启用数据库配置前必须先在文件里打开总闸
config :pleroma, configurable_from_database: true

• mix pleroma.config migrate_to_db：把文件配置整体搬进数据库，此后以库内值为准。
• mix pleroma.config migrate_from_db [--env=prod] [-d] [--path=/tmp]：把库内配置导出回文件 config/env.exported_from_db.secret.exs。
• mix pleroma.config dump [group [key]] / groups / delete [--force] / [--force] reset：查看、删除、清空库内配置。
• mix pleroma.config dump_to_file pleroma mrf_simple /tmp/mrf_simple.json + load_from_file：以 JSON 批量改复杂参数（如 MRF），官方原文提示 "This will overwrite any existing value in the database, and can cause crashes if you do not have exactly the correct formatting."
• mix pleroma.config filter_whitelisted：清除未被 :database_config_whitelist 白名单放行的库内配置。

实测边界行为：总闸为 false 时任何 config 子命令直接拒绝——

=== config groups (db-configurable=false) ===
ConfigDB not enabled. Please check the value of :configurable_from_database in your configuration.

官方文档同时提示：改配置后多数项需要重启实例生效，管理端可访问 /api/v1/pleroma/admin/restart 软重启。

十、参数生效实测验证（改 description 全链路）

操作：在 prod.secret.exs 追加 config :pleroma, :instance, description: "Akkoma 测试实例：quzuo.net 配置实测"，然后重启应用服务：

 Container akkoma-3.20.1-app Restarting
 Container akkoma-3.20.1-app Started

改前 /api/v1/instance 实测回显（节选）：

{"description":"Akkoma: The cooler fediverse server","title":"Akkoma Test","max_toot_chars":5000,"upload_limit":16000000,"registrations":true}

改后同一接口实测回显：

{"version": "2.7.2 (compatible; Akkoma 3.20.1-0-gbc62dd8)", "description": "Akkoma 测试实例：quzuo.net 配置实测", "title": "Akkoma Test", "max_toot_chars": 5000, "upload_limit": 16000000, "registrations": true}

结论：文件配置改动必须重启才生效（软重启亦可），生效后立即反映到 Mastodon 兼容 API；/nodeinfo/2.0.json 的 metadata.nodeName/nodeDescription 同步（实测含 "nodeName":"Akkoma Test" 与 postFormats 五种格式 ["text/plain","text/html","text/markdown","text/bbcode","text/x.misskeymarkdown"]）。

十一、常见坑小结

1. url.host 先想清楚再 gen：域名会烧进历史数据的 AP ID，事后改域名需要 MRF/迁移工具补救。
2. http.ip 默认 127.0.0.1：容器/反代部署必改 0.0.0.0，但改完务必用宿主端口映射或反代限制暴露面。
3. configurable_from_database 与文件配置互踩：开库配置后文件同名项被库值覆盖，排障时先 mix pleroma.config dump 看库里存了什么。
4. 改配置不重启不生效：文件层没有任何热加载（实测第十章）；库配置层部分项即时生效、部分仍需重启。
5. 密钥文件权限：instance gen 生成即 0640，prod.secret.exs 含 secret_key_base/default_signer/VAPID 私钥，禁止提交仓库（文件头注释原文 "should not be committed to a repo"）。

十二、小结与关联

Akkoma 的配置哲学是「一次 gen、少量覆盖、双轨可选」：instance gen 生成密钥与骨架，实例差异集中在 prod.secret.exs 八十余行内；需要管理端在线调参时再打开 configurable_from_database 走数据库层。参数全集与逐项文档在仓库 config/description.exs（106KB 机器可读），管理 UI 即由它渲染。

• 选型与架构背景：《Akkoma 3.20.1 介绍与选型指南》
• 部署全流程实测：《Akkoma 3.20.1 Docker Compose 部署指南》
• 配置迁移与全部 CLI 任务：《Akkoma 3.20.1 常用 CLI 命令与工具详解》