Pleroma 2.11.0 配置参数详解

Pleroma 2.11.0 配置体系逐层拆解:出厂 docker.exs/secret.exs/用户 config.exs/数据库轨四层加载链与优先级、Endpoint/instance/Repo/Upload/media_proxy/frontends/MRF/chat 各参数组 pleroma rpc 实查解说、config 双轨迁移八子命令与 help 子命令不存在的踩坑实录、公共实例生产模板。

PleromaPleromaFediverseElixirPostgreSQLActivityPub2026/11/02

Pleroma 2.11.0 配置参数详解

本文以 Docker Compose 官方镜像路线的在跑实例为对象,拆解 Pleroma 2.11.0 的「内置配置 → secret.exs → 用户 config.exs → 数据库轨」四层配置体系,逐组讲解 Endpoint、instance、Repo、Upload、media_proxy、frontends、MRF 等关键参数组,全部配置值为 2026-11-02 经 pleroma rpc 实查回显(敏感密钥已脱敏),双轨迁移命令附实测输出与踩坑。

一、配置体系总览

1.1 四层加载链(官方镜像路线)

Pleroma 是 Elixir/OTP 应用,配置本质是编译期/启动期读取的 .exs 文件链。官方镜像出厂即定义了完整加载顺序(来源:镜像内 /etc/pleroma/config.exs,即仓库 config/docker.exs,逐行实查):

层文件生成方式内容
① 出厂层/etc/pleroma/config.exs构建时烘焙进镜像用环境变量组装 Endpoint/instance/Repo/上传目录(见 1.2)
② 密钥层/var/lib/pleroma/secret.exs首启自动生成(不存在则随机生成后写入)secret_key_base、signing_salt、Web Push VAPID 公私钥对
③ 用户层/var/lib/pleroma/config.exs首启自动生成空模板,人工维护「环境变量之外的额外配置」,import_config 晚于前两层、优先级最高
④ 数据库轨(可选)configurable_from_database: true 后迁入 DBpleroma_ctl config migrate_to_db运行时可改的配置集(见第五章)

docker.exs 中对应逻辑(实查原文件节选):

# We can't store the secrets in this file, since this is baked into the docker image
if not File.exists?("/var/lib/pleroma/secret.exs") do
  secret = :crypto.strong_rand_bytes(64) |> Base.encode64() |> binary_part(0, 64)
  signing_salt = :crypto.strong_rand_bytes(8) |> Base.encode64() |> binary_part(0, 8)
  {web_push_public_key, web_push_private_key} = :crypto.generate_key(:ecdh, :prime256v1)
  ...
  File.write("/var/lib/pleroma/secret.exs", secret_file)
end

import_config("/var/lib/pleroma/secret.exs")

# For additional user config
if File.exists?("/var/lib/pleroma/config.exs"),
  do: import_config("/var/lib/pleroma/config.exs"),
  else:
    File.write("/var/lib/pleroma/config.exs", """
    import Config

    # For additional configuration outside of environmental variables
    """)

⚠️ 注意:②③ 两层都落在数据目录 /var/lib/pleroma(compose 中即 ./data bind 挂载)。secret.exs 丢失 = Cookie 签名密钥丢失,所有用户会话失效、VAPID 推送密钥作废,必须纳入备份。裸机 OTP 路线没有 ①② 的自动生成逻辑,配置链为 config.json/config.secret.exs/config/pleroma*.exs 与 PLEROMA_CONFIG_PATH,但「用户文件覆盖出厂默认」的优先级思想一致。

1.2 出厂层支持的环境变量(官方镜像唯一「免改文件」配置面)

变量落入配置项出厂默认
DOMAINPleroma.Web.Endpoint url.hostlocalhost
INSTANCE_NAME:instance namePleroma
ADMIN_EMAIL:instance email无
NOTIFY_EMAIL:instance notify_email无
DB_HOST/DB_PORT/DB_NAME/DB_USERPleroma.Repo hostname/port/database/usernamedb/5432/pleroma/pleroma
DB_PASSPleroma.Repo passwordSystem.fetch_env! 强制要求,不设直接启动失败

出厂层还固定写入:limit: 5000、registrations_open: false(默认关注册)、healthcheck: true、pool_size: 10、static_dir: "/var/lib/pleroma/static"、Pleroma.Uploaders.Local uploads: "/var/lib/pleroma/uploads"、:database rum_enabled: false、VAPID subject: "mailto:#{NOTIFY_EMAIL}"。

⚠️ 注意:url 出厂写死 scheme: "https", port: 443——官方假设反代终结 TLS。无域名直连测试时须在用户层覆盖(实录见部署篇排障 ②)。

二、Pleroma.Web.Endpoint(实例身份层)

实查回显(pleroma rpc 'IO.inspect(Pleroma.Config.get(Pleroma.Web.Endpoint))',密钥脱敏):

[
  live_view: [signing_salt: "<脱敏>"],
  render_errors: [view: Pleroma.Web.ErrorView, accepts: ["json"]],
  pubsub_server: Pleroma.PubSub,
  secure_cookie_flag: true,
  extra_cookie_attrs: ["SameSite=Lax"],
  protocol: "http",
  http: [ip: {0, 0, 0, 0}, port: 4000],
  secret_key_base: "<脱敏,64 字节 base64>",
  signing_salt: "<脱敏,8 字节>",
  url: [host: "localhost", scheme: "http", port: 8148]   # 用户层覆盖后的实测值
]
  • url:实例对外的身份基址,所有 AP actor/对象 URL、WebFinger、nodeinfo 均由它派生。开放联邦后不可更改(改 = 换身份,历史对象全部失联);
  • http:实际监听地址/端口,出厂 0.0.0.0:4000;生产应由反代转发,并用防火墙/网络策略禁止外部直连 4000;
  • secret_key_base/signing_salt:会话 Cookie 与各类签名令牌密钥,位于 secret.exs,泄露即可伪造任意用户会话;
  • secure_cookie_flag: true:Cookie 仅 HTTPS 下发——本地 http 测试若遇登录态异常,可在用户层临时置 false(生产保持 true)。

三、:instance 组(实例政策层,核心)

实查完整回显(pleroma rpc 'IO.inspect(Pleroma.Config.get(:instance), limit: :infinity)',2026-11-02,节选照抄):

[
  description: "Pleroma: An efficient and flexible fediverse server",
  short_description: "",
  background_image: "/images/city.jpg",
  instance_thumbnail: "/instance/thumbnail.jpeg",
  favicon: "/favicon.png",
  description_limit: 5000,
  remote_limit: 100000,
  upload_limit: 16000000,
  avatar_upload_limit: 2000000,
  background_upload_limit: 4000000,
  banner_upload_limit: 4000000,
  poll_limits: %{
    max_expiration: 31536000,
    max_option_chars: 200,
    max_options: 20,
    min_expiration: 0
  },
  invites_enabled: false,
  account_activation_required: false,
  account_approval_required: false,
  federating: true,
  federation_incoming_replies_max_depth: 100,
  allow_relay: true,
  public: true,
  quarantined_instances: [],
  rejected_instances: [],
  allowed_post_formats: ["text/plain", "text/html", "text/markdown",
   "text/bbcode", "text/x.misskeymarkdown"],
  ...
  remote_post_retention_days: 90,
  skip_thread_containment: true,
  limit_to_local_content: :unauthenticated,
  user_bio_length: 5000,
  user_name_length: 100,
  max_account_fields: 10,
  ...
  multi_factor_authentication: [
    totp: [digits: 6, period: 30],
    backup_codes: [number: 5, length: 16]
  ],
  show_reactions: true,
  password_reset_token_validity: 86400,
  profile_directory: true,
  admin_privileges: [:users_read, :users_manage_invites, ... :statistics_read],
  moderator_privileges: [:messages_delete, :reports_manage_reports],
  ...
  max_media_attachments: 1000,
  name: "Pleroma Demo",
  email: "admin@example.com",
  notify_email: "notifications@example.com",
  limit: 5000,
  registrations_open: false,
  healthcheck: true,
  static_dir: "/var/lib/pleroma/static"
]

3.1 逐键讲解(按决策重要度排序)

发帖与容量

键实测值说明
limit5000本实例用户贴文长度上限(字符);Mastodon 客户端默认按此协商
remote_limit100000远端贴文长度上限,防超大贴撑爆解析
upload_limit16000000附件总大小 16MB;改大需同步反代 client_max_body_size
avatar/banner/background_upload_limit2M/4M/4M分类型图片限额
max_media_attachments1000单贴附件数上限(官方自述「不限数量」的实际落点)
allowed_post_formats5 种含 text/x.misskeymarkdown——2.11 主线原生接受 MFM 输入格式,另支持 BBCode/Markdown/HTML/plain
poll_limits20 项/200 字符/1 年投票参数组

注册与准入

键实测值说明
registrations_openfalse出厂关注册;公共实例开 true,或配合 invites_enabled: false→true 走邀请制
account_activation_requiredfalse需邮件激活(需 SMTP 配好)
account_approval_requiredfalse需管理员审批(配合 registration_reason_length: 500 收集申请理由)

联邦与治理

键实测值说明
federatingtrue联邦总开关,false 变孤岛实例
publictrue公开实例(进实例目录)
federation_incoming_replies_max_depth100入站回复链拉取深度,防深链攻击
quarantined_instances / rejected_instances[]隔离(可收件不可发)/ 拒收域名清单,配合 MRF TagPolicy 使用
remote_post_retention_days90远端贴保留天数(清理任务用)
limit_to_local_content:unauthenticated未登录者只见本地内容(防爬虫全量抓取)
skip_thread_containmenttrue帖子含被屏蔽作者时整贴隐藏
allow_relaytrue允许大中继订阅(pleroma_ctl relay 管理)

界面与角色

键实测值说明
name/descriptionPleroma Demo / ...实例名片,进 nodeinfo
email/notify_emailadmin@ / notifications@对外联系邮箱 / 发件人地址
healthchecktrue开放 /api/pleroma/healthcheck 探活端点
show_reactions/profile_directorytrueemoji 回应展示 / 用户目录
admin_privileges/moderator_privileges见回显角色权限白名单(细粒度原子列表)
multi_factor_authenticationtotp+backup_codes2FA 参数组

3.2 文本格式说明

💡 说明:allowed_post_formats 默认即含 Misskey Markdown,这是 2.11 主线与早期认知(「MFM 是 Akkoma 专属」)的重要差异点——MFM 输入主线可解析;而无限编辑次数、引用转发交互等「表达体验」层仍是 Akkoma 更激进(对照见选型篇)。

四、数据、上传、媒体与前端组

4.1 Pleroma.Repo(数据库连接)

实查回显:

[adapter: Ecto.Adapters.Postgres, username: "pleroma", database: "pleroma",
 hostname: "db", port: "5432", pool_size: 10]
  • 全部来自环境变量(1.2 表);pool_size: 10 为出厂值,小实例够用,高并发可加 DB_POOL_SIZE?——注意:出厂 docker.exs 并未提供 pool_size 的环境变量,改它须在用户层 config.exs 覆盖 config :pleroma, Pleroma.Repo, pool_size: 20;
  • 连接池为 Ecto 标准 queue_target/queue_interval 模型,PG 侧无需 pgbouncer(官方文档提供可选 pgbouncer 指南)。

4.2 :database

[rum_enabled: false]

RUM 是 PostgreSQL 索引扩展(加速全文检索倒排),false 表示用内置 GIN/pg_trgm,无需装 RUM 扩展;追求检索性能且库为自管时可置 true 并安装扩展。

4.3 Pleroma.Upload / Uploaders.Local

实查回显:

# Pleroma.Upload
[uploader: Pleroma.Uploaders.Local,
 filters: [Pleroma.Upload.Filter.Dedupe],
 link_name: false,
 proxy_remote: false,
 filename_display_max_length: 30,
 default_description: nil,
 base_url: nil,
 allowed_mime_types: ["image", "audio", "video"]]

# Pleroma.Uploaders.Local
[uploads: "/var/lib/pleroma/uploads"]
  • uploader 可切 Pleroma.Uploaders.S3(对象存储路线,配 Pleroma.S3 组);
  • filters 追加 Pleroma.Upload.Filter.Mogrify(ImageMagick 处理)/ExiftoolStrip(EXIF 剥离,隐私向);镜像已内置 exiftool/vips 依赖,开箱可用;
  • base_url:CDN/独立媒体域名场景设置;
  • allowed_mime_types 只按大类过滤。

4.4 :media_proxy

[enabled: false,
 invalidation: [enabled: false, provider: Pleroma.Web.MediaProxy.Invalidation.Script],
 proxy_opts: [redirect_on_failure: false, max_body_length: 26214400,
   max_read_duration: 30000, http: [follow_redirect: true, pool: :media]],
 whitelist: []]

默认关闭;开启(enabled: true)后远端图片经本实例签名 URL 代理,防 IP 泄露与混合内容告警,whitelist 放行不走代理的域名。

4.5 :frontends(可插拔前端机制)

实查 available 注册表含 7 个前端:

["admin-fe", "fedi-fe", "glitch-lily", "kenoma", "pl-fe", "pleroma-fe", "soapbox"]

每个条目带 git/build_url/ref 元数据(如 admin-fe 从 git.pleroma.social/api/packages/pleroma/generic/admin-fe-builds/${ref}/latest.zip 拉构建产物)。primary/admin 实查为 nil——官方镜像出厂把 pleroma-fe 直接打进制品 priv 目录,未走 frontends 安装机制;换前端用 mix pleroma.frontend install/switch/uninstall(详见 CLI 篇,含 frontend list 不存在的实测报错)。

4.6 :mrf(消息路由过滤)

[policies: [Pleroma.Web.ActivityPub.MRF.ObjectAgePolicy,
  Pleroma.Web.ActivityPub.MRF.TagPolicy, Pleroma.Web.ActivityPub.MRF.InlineQuotePolicy],
 transparency: true, transparency_exclusions: []]

出厂即启用 3 个策略:对象年龄(配合 remote_post_retention_days)、标签(配合 quarantined/rejected 域名)、内联引用规范化。自定义策略(如 SimplePolicy 关键词过滤、MediaProxyRewriter)追加到此列表;transparency: true 让被过滤贴对作者可见原因。

4.7 :chat 与 :http

  • :chat 关键字组实查为 nil,但模块键 Pleroma.Chat 实查为 [enabled: true]——主线聊天(私信/群聊)出厂即启用,nodeinfo features 中的 chat/pleroma_chat_messages 由此而来;如需关闭在用户层写 config :pleroma, Pleroma.Chat, enabled: false;
  • :http 实查 [proxy_url: nil, send_user_agent: true, user_agent: :default, adapter: []]——出站联邦请求经 proxy_url 可挂 TOR/HTTP 代理。

五、配置双轨:文件 ↔ 数据库

Pleroma 支持把配置整体迁入数据库(configurable_from_database: true 后),AdminAPI/前端管理页即可运行时改配置。CLI 子命令全集(来源:官方文档 Transferring the config to/from the database 页 + 实查):

命令(OTP 形态)作用
pleroma_ctl config migrate_to_db文件配置 → DB(前提:先写入 config :pleroma, configurable_from_database: true)
pleroma_ctl config migrate_from_db [--env=<env>] [-d] [--path=<path>]DB → env.exported_from_db.secret.exs 文件
pleroma_ctl config dump [group [key]]打印 DB 中某组/某键的值
pleroma_ctl config groups列出 DB 中的配置组
pleroma_ctl config delete [--force] group [key]删除 DB 中某组/键
pleroma_ctl config [--force] reset清空 DB 配置
pleroma_ctl config fix_mrf_policies清除 DB 中不存在的 MRF 模块(救砖命令:误配 MRF 导致起不来时用)
pleroma_ctl config filter_whitelisted按 :database_config_whitelist 白名单清洗 DB 配置

实测(本实例未开 DB 轨):

$ docker exec pleroma-2.11.0-app /opt/pleroma/bin/pleroma_ctl config groups
(无输出——DB 配置表为空,当前实例配置全在文件轨)

⚠️ 排障实录:2.11 的 config 任务没有 help/list 子命令,传入即抛(原样照抄):

** (FunctionClauseError) no function clause matching in Mix.Tasks.Pleroma.Config.run/1
    The following arguments were given to Mix.Tasks.Pleroma.Config.run/1:
        # 1
        ["help"]
    (pleroma 2.11.0-develop) lib/mix/tasks/pleroma/config.ex:17: Mix.Tasks.Pleroma.Config.run/1

查子命令清单以官方文档页为准,勿凭其他 mix 任务习惯猜参数。

⚠️ 注意(双轨互斥):configurable_from_database: true 后文件轨的多数配置不再生效(DB 优先),回退须先 migrate_from_db 导出再置回 false,否则改文件无效果、排查极易绕晕。

六、生产配置模板(用户层 config.exs)

综合以上参数组,公共实例最小生产模板(写入 /var/lib/pleroma/config.exs,重启生效):

import Config

# 1. 实例身份(真实域名 + TLS,反代终结)
config :pleroma, Pleroma.Web.Endpoint,
  url: [host: "social.example.com", scheme: "https", port: 443]

# 2. 实例名片与准入
config :pleroma, :instance,
  name: "Example Social",
  description: "A friendly Pleroma instance",
  registrations_open: true,
  account_approval_required: true,
  upload_limit: 20_000_000

# 3. 媒体代理(防 IP 泄露)
config :pleroma, :media_proxy, enabled: true

# 4. 上传走 S3(可选,替代本地盘)
config :pleroma, Pleroma.Upload, uploader: Pleroma.Uploaders.S3, base_url: "https://cdn.example.com"
config :pleroma, Pleroma.S3, bucket: "pleroma", host: "s3.example.com",
  path_style: true, bucket_namespace: "uploads"

# 5. 联邦治理:拒收名单 + 关键词过滤
config :pleroma, :instance, rejected_instances: ["spam.example.net"]
config :pleroma, Pleroma.Web.ActivityPub.MRF.SimplePolicy,
  message_rejections: [{"(?i)badword", "Pleroma"}]
config :pleroma, :mrf, policies: [Pleroma.Web.ActivityPub.MRF.SimplePolicy |
  Pleroma.Config.get([:mrf, :policies])]

# 6. 连接池调优(并发高时)
config :pleroma, Pleroma.Repo, pool_size: 20

生效方式:docker compose restart pleroma(OTP 路线 bin/pleroma stop && bin/pleroma start)。改完可用第二章各 pleroma rpc 命令复核实际加载值。

七、要点回顾

  1. 四层加载链:出厂 docker.exs(环境变量)→ secret.exs(自动生成,必备份)→ 用户 config.exs(人工维护,优先级最高)→ 可选 DB 轨(运行时可改);
  2. 实例身份:Endpoint url 一经开放联邦不可改;secret_key_base 泄露即会话伪造;
  3. 默认安全:registrations_open: false、limit_to_local_content: :unauthenticated、secure_cookie_flag: true——公共实例按需放开而非盲目全开;
  4. 依赖链极简:配置面里外部服务只有 Pleroma.Repo(PostgreSQL)一环,无 Redis 组、无 ES 组,媒体处理走内置 exiftool/vips;
  5. 双轨迁移:上 DB 轨前先 configurable_from_database: true,回退先 migrate_from_db;起不来砖了用 config fix_mrf_policies;
  6. 2.11 主线已支持 MFM 输入格式(allowed_post_formats 含 text/x.misskeymarkdown),选型时勿再用旧认知。

八、站内阅读


实测说明:本文所有配置值回显产生于 2026-11-02 的在跑实例(pleroma rpc 直查运行节点);secret_key_base、signing_salt 等密钥值已脱敏,其余逐行照抄。

Pleroma 2.11.0 配置参数详解 - Quzuo