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 子命令不存在的踩坑实录、公共实例生产模板。
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 后迁入 DB | pleroma_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 中即./databind 挂载)。secret.exs丢失 = Cookie 签名密钥丢失,所有用户会话失效、VAPID 推送密钥作废,必须纳入备份。裸机 OTP 路线没有 ①② 的自动生成逻辑,配置链为config.json/config.secret.exs/config/pleroma*.exs与PLEROMA_CONFIG_PATH,但「用户文件覆盖出厂默认」的优先级思想一致。
1.2 出厂层支持的环境变量(官方镜像唯一「免改文件」配置面)
| 变量 | 落入配置项 | 出厂默认 |
|---|---|---|
DOMAIN | Pleroma.Web.Endpoint url.host | localhost |
INSTANCE_NAME | :instance name | Pleroma |
ADMIN_EMAIL | :instance email | 无 |
NOTIFY_EMAIL | :instance notify_email | 无 |
DB_HOST/DB_PORT/DB_NAME/DB_USER | Pleroma.Repo hostname/port/database/username | db/5432/pleroma/pleroma |
DB_PASS | Pleroma.Repo password | System.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 逐键讲解(按决策重要度排序)
发帖与容量
| 键 | 实测值 | 说明 |
|---|---|---|
limit | 5000 | 本实例用户贴文长度上限(字符);Mastodon 客户端默认按此协商 |
remote_limit | 100000 | 远端贴文长度上限,防超大贴撑爆解析 |
upload_limit | 16000000 | 附件总大小 16MB;改大需同步反代 client_max_body_size |
avatar/banner/background_upload_limit | 2M/4M/4M | 分类型图片限额 |
max_media_attachments | 1000 | 单贴附件数上限(官方自述「不限数量」的实际落点) |
allowed_post_formats | 5 种 | 含 text/x.misskeymarkdown——2.11 主线原生接受 MFM 输入格式,另支持 BBCode/Markdown/HTML/plain |
poll_limits | 20 项/200 字符/1 年 | 投票参数组 |
注册与准入
| 键 | 实测值 | 说明 |
|---|---|---|
registrations_open | false | 出厂关注册;公共实例开 true,或配合 invites_enabled: false→true 走邀请制 |
account_activation_required | false | 需邮件激活(需 SMTP 配好) |
account_approval_required | false | 需管理员审批(配合 registration_reason_length: 500 收集申请理由) |
联邦与治理
| 键 | 实测值 | 说明 |
|---|---|---|
federating | true | 联邦总开关,false 变孤岛实例 |
public | true | 公开实例(进实例目录) |
federation_incoming_replies_max_depth | 100 | 入站回复链拉取深度,防深链攻击 |
quarantined_instances / rejected_instances | [] | 隔离(可收件不可发)/ 拒收域名清单,配合 MRF TagPolicy 使用 |
remote_post_retention_days | 90 | 远端贴保留天数(清理任务用) |
limit_to_local_content | :unauthenticated | 未登录者只见本地内容(防爬虫全量抓取) |
skip_thread_containment | true | 帖子含被屏蔽作者时整贴隐藏 |
allow_relay | true | 允许大中继订阅(pleroma_ctl relay 管理) |
界面与角色
| 键 | 实测值 | 说明 |
|---|---|---|
name/description | Pleroma Demo / ... | 实例名片,进 nodeinfo |
email/notify_email | admin@ / notifications@ | 对外联系邮箱 / 发件人地址 |
healthcheck | true | 开放 /api/pleroma/healthcheck 探活端点 |
show_reactions/profile_directory | true | emoji 回应展示 / 用户目录 |
admin_privileges/moderator_privileges | 见回显 | 角色权限白名单(细粒度原子列表) |
multi_factor_authentication | totp+backup_codes | 2FA 参数组 |
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 命令复核实际加载值。
七、要点回顾
- 四层加载链:出厂 docker.exs(环境变量)→ secret.exs(自动生成,必备份)→ 用户 config.exs(人工维护,优先级最高)→ 可选 DB 轨(运行时可改);
- 实例身份:
Endpoint url一经开放联邦不可改;secret_key_base泄露即会话伪造; - 默认安全:
registrations_open: false、limit_to_local_content: :unauthenticated、secure_cookie_flag: true——公共实例按需放开而非盲目全开; - 依赖链极简:配置面里外部服务只有
Pleroma.Repo(PostgreSQL)一环,无 Redis 组、无 ES 组,媒体处理走内置 exiftool/vips; - 双轨迁移:上 DB 轨前先
configurable_from_database: true,回退先migrate_from_db;起不来砖了用config fix_mrf_policies; - 2.11 主线已支持 MFM 输入格式(
allowed_post_formats含text/x.misskeymarkdown),选型时勿再用旧认知。
八、站内阅读
- 部署与实测环境:《Pleroma 2.11.0 Docker Compose 部署指南》
- 架构与版本溯源:《Pleroma 2.11.0 介绍与选型指南》
- 前端安装/切换与配置类 CLI:《Pleroma 2.11.0 常用 CLI 命令详解》
实测说明:本文所有配置值回显产生于 2026-11-02 的在跑实例(pleroma rpc 直查运行节点);secret_key_base、signing_salt 等密钥值已脱敏,其余逐行照抄。