PieFed 1.8.10 配置参数详解

目标：以 PieFed 1.8.10 实测环境为基准，系统梳理配置加载链（.env.docker → config.py Config 类 → 应用运行时）、全部环境变量的分组语义与默认值，覆盖身份安全、网络域名、数据库、缓存/队列/联邦保护、邮件与退信、媒体与对象存储、API、反滥用治理、内容保留、第三方集成与进程并发，并给出生产配置模板与 FAQ；所有"实测生效值"均来自部署环境回显（2026-11-02）。

一、环境信息

• PieFed：v1.8.10（Codeberg rimu/pyfedi，app/constants.py 钉定）
• 运行时：Python 3.13 + Flask + Gunicorn 26.2.0（gthread）+ Celery + FastAPI（实时通知）
• 依赖：PostgreSQL 17、Redis 6.2
• 配置载体：仓库根 .env.docker（compose env_file 注入）与 config.py（load_dotenv('.env')，裸机形态）
• 实测实例：SERVER_NAME='127.0.0.1:8129'，演示账号 admin / q1w2e3r4

站内配套：《PieFed 1.8.10 介绍与选型指南》、《PieFed 1.8.10 Docker Compose 部署指南》、《PieFed 1.8.10 常用 CLI 命令与工具详解》。

二、配置加载链与修改方式

PieFed 没有独立的配置文件（如 YAML/JSON 站点配置），全部服务端参数走环境变量 → Flask Config 类一条链：

.env.docker（compose env_file 注入进程环境）
    └→ config.py 的 class Config：逐项 os.environ.get(...) 取默认值
            └→ app/__init__.py 加载 Config → current_app.config

config.py 关键实现（实测源码）：

basedir = os.path.abspath(os.path.dirname(__file__))
load_dotenv(os.path.join(basedir, '.env'))     # 裸机形态读 .env；compose 形态读 .env.docker

class Config(object):
    SERVER_NAME = os.environ.get('SERVER_NAME').lower() or 'localhost'
    SECRET_KEY = os.environ.get('SECRET_KEY')
    SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL') or 'sqlite:///' + ...

修改方式：编辑 .env.docker 后需重启应用进程生效（docker compose up -d web celery piefednotifs 或宿主等价重启）；数值型变量有安全转换（safe_int_env 非法值回落默认并告警）。核对生效值首选内置自检命令：

docker exec -it piefed_app1 sh -c 'export FLASK_APP=pyfedi.py && flask config_check'

实测回显（节选，完整输出见 D1 4.6 节）：

1. Checking required environment variables...
   ✅ SERVER_NAME is configured: 127.0.0.1:8129
   ✅ SECRET_KEY is configured
   ✅ DATABASE_URL is configured (PostgreSQL)
   ✅ MAIL_PORT is valid: 25
   ✅ DB_POOL_SIZE is valid: 10
   ✅ DB_MAX_OVERFLOW is valid: 30
2. Checking database connection... ✅ Database connection successful
3. Checking Redis connection... ✅ Redis connection successful
...
⚠️  2 warning(s) found:
   ⚠️  Mail server not configured - email functionality will be disabled
   ⚠️  SERVER_NAME not properly configured for federation

另有站点级动态设置存于数据库 Settings 表（/admin 面板维护：站点名、描述、注册开关、默认版块等），与环境变量分工——环境变量定"实例怎么跑"，面板定"站点长什么样"。nodeinfo 的 openRegistrations:false 即面板侧注册开关的投影。

三、参数总览（分组）

四、核心参数分类详解

4.1 身份与安全：SECRET_KEY / SESSION_COOKIE_*

SECRET_KEY 官方要求 ≥32 位随机字符（实测用 secrets.token_hex(32) 生成 64 位十六进制）。它同时是 Flask 会话签名与 Alpha API JWT 的签名密钥——更换等于全员登出且已发 JWT 全部失效。SESSION_COOKIE_SECURE 默认开：纯 HTTP 测试实例若浏览器拿不到会话，把它置 0（生产必须保持 1 并配 SSL）。

4.2 网络与域名：SERVER_NAME / HTTP_PROTOCOL

SERVER_NAME 是全局身份基准：ActivityPub 的 actor id、社区/用户 URL 都由它派生（实测 nodeinfo 与 API 返回的 actor_id":"https://127.0.0.1:8129/c/techops"）。官方红线提醒：该值确定后变更 = 清库重来；config_check 对非域名形态给出 ⚠️ SERVER_NAME not properly configured for federation（实测回显见上），测试环境可接受，联邦实例必须改为真实域名并同步 HTTP_PROTOCOL。

4.3 数据库：DATABASE_URL 与连接池

格式固定 postgresql+psycopg2://<user>:<pass>@<host>/<db>，compose 形态主机名即服务名 db。DB_POOL_SIZE=10、DB_MAX_OVERFLOW=30 为每进程连接池（Gunicorn 多 worker 时总连接 = 池 × worker 数，需与 PostgreSQL max_connections=150 匹配——实测 4 worker 场景合计 ≤160，贴边；加 worker 先加 max_connections）。PostgreSQL 侧调优参数（shared_buffers 等）在 compose 的 db 服务命令行定义，详见 B2 第五节依赖链。init-db 强校验库编码 UTF8，中文社区必满足。

4.4 缓存、队列与联邦水位

• CACHE_TYPE：compose 模板用 RedisCache（DB0），裸机默认 FileSystemCache（/dev/shm/pyfedi）。
• CELERY_BROKER_URL 指 Redis DB1，与缓存分库，避免队列膨胀挤爆缓存。
• REDIS_MEMORY_LIMIT（默认 200 MB）是 PieFed 特色保护：flask send-queue 每轮检查 Redis total.allocated，超限即打印 Redis memory is quite full - stopping send queue... 并置 pause_federation 键暂停联邦 600 秒（源码实测逻辑，D1 4.5 节有运行验证）。-1 关闭检查。

4.5 邮件与退信：MAIL_* / BOUNCE_*

MAIL_SERVER 留空则邮件功能整体关闭（config_check 告警 Mail server not configured，实测）。MAIL_USE_TLS 的判定是"行不存在=关，存在即开"（os.environ.get('MAIL_USE_TLS') is not None），官方模板注释"不用 TLS 就删掉这行，别设 False"——设 MAIL_USE_TLS=False 反而会被判为开。BOUNCE_ADDRESS + BOUNCE_HOST/TYPE(imap|pop3)/USERNAME/PASSWORD 配置退信箱，flask process_email_bounces 定期回收（官方警告：该收件箱所有邮件会被删除，务必用专用地址）。

4.6 媒体与对象存储：MEDIA_IMAGE_* / S3_*

图片处理链：上传原图 → 长边压至 MEDIA_IMAGE_MAX_DIMENSION=2000 → 生成 medium（默认 WEBP/93，env.sample 示例改 JPEG/90）与 thumbnail（WEBP/93）。FILE_UPLOAD_QUOTA=52428800（50 MB）只管正文插图，帖子配图走独立通道。S3 兼容存储七件套（S3_REGION/ENDPOINT/BUCKET/ACCESS_KEY/ACCESS_SECRET/PUBLIC_URL/S3_PUBLIC_ACL）+ AWS_REGION 启用后，配 flask move-files-to-s3 系列命令把存量迁走（官方有 Backblaze B2 / Wasabi 专文）。

4.7 API：ENABLE_ALPHA_API 等

ENABLE_ALPHA_API='true' 打开 /api/alpha/*（实测登录返回 232 字符 JWT）。SERVE_API_DOCS 打开 Swagger（/api/alpha/swagger）。RATELIMIT_ENABLED 默认开，登录等敏感端点有独立限流（实测 login 挂 20/hour 桶）；SKIP_RATE_LIMIT_IPS 默认放行 127.0.0.1。JWT_EXPIRY_DAYS=365 控制令牌寿命。CORS_ALLOW_ORIGIN 默认 *，纯自用可收紧。

4.8 反滥用与治理

• VOTE_QUOTA=240：每人每日投票上限（联邦大实例调高，小实例可保持）。
• ANOOBIS=1 + 难度 19/12：对疑似爬虫下发工作量证明挑战，桌面/移动分档。
• SPICY_UNDER_10/30/60：按受众年龄分层的 NSFW 内容分级阈值（compose 模板示例 2.5/1.85/1.25，默认 1.0 即不额外收紧）。
• FLAG_THROWAWAY_EMAILS：开启后消费一次性邮箱域名表（即 B2 排障 10.1 中 raw.githubusercontent.com 那份 domains.txt）——不开此开关，那份表缺失无影响。
• ALLOW_AI_CRAWLERS、DETECT_AI_ENDPOINT、CHAN_DETECTION_ENDPOINT：AI 爬虫放行与内容检测外挂点。

4.9 内容保留与归档

ARCHIVE_POSTS=N（月）：N 个月前的帖子关评论、停投票并把图片数据归档到 S3/磁盘，控制库增长；KEEP_LOCAL/REMOTE_VOTE_DATA_TIME（默认 6 个月，-1 永删）清理投票明细；DEFAULT_CONTENT_RETENTION（-1=永久）是远程社区内容保留默认值（每社区可在面板覆写）；BOT_CONTENT_RETENTION=6 专管 bot 无回复内容。旗舰实例 18 个月 100 GB 的口径下，小盘实例建议 ARCHIVE_POSTS=12 起步。

4.10 进程并发：GUNICORN_WORKERS / CELERY_CONCURRENCY

gunicorn.conf.py（bind 挂载可改，实测源码）：worker 数 = GUNICORN_WORKERS 或 max(4, CPU核数//2)，threads=2、worker_class='gthread'、max_requests=2000（±50 抖动滚动重启防内存漂移）、bind='0.0.0.0:5000'、日志走 stdout。CELERY_CONCURRENCY 默认 4（celery 入口脚本读取）。实测空载 web 常驻 1.076 GiB / celery 534 MiB（B2 4.7 节 stats），4 GB 内存实例可 GUNICORN_WORKERS=2 + CELERY_CONCURRENCY=2 起步。

五、生产配置模板

域名 forum.example.com、PostgreSQL/Redis 同栈、S3 外置、开邮件与治理的最小生产 .env.docker：

SECRET_KEY='<64 位随机>'
SERVER_NAME='forum.example.com'
HTTP_PROTOCOL='https'

POSTGRES_USER='piefed'
POSTGRES_PASSWORD='<强口令>'
POSTGRES_DB='piefed'
DATABASE_URL=postgresql+psycopg2://piefed:<强口令>@db/piefed

CACHE_TYPE='RedisCache'
CACHE_REDIS_URL='redis://redis:6379/0'
CELERY_BROKER_URL='redis://redis:6379/1'
REDIS_MEMORY_LIMIT=300000000

MAIL_SERVER='smtp.example.com'
MAIL_PORT=465
MAIL_USE_TLS=True
MAIL_USERNAME='noreply@example.com'
MAIL_PASSWORD='<口令>'
MAIL_FROM='noreply@example.com'
ERRORS_TO='admin@example.com'

ENABLE_ALPHA_API='true'
VOTE_QUOTA=240
ANOOBIS=1
SPICY_UNDER_10=2.5
SPICY_UNDER_30=1.85
SPICY_UNDER_60=1.25
ARCHIVE_POSTS=12
FLAG_THROWAWAY_EMAILS=1

AWS_REGION='ap-southeast-2'
S3_ENDPOINT='https://s3.<provider>'
S3_BUCKET='piefed-media'
S3_ACCESS_KEY='<key>'
S3_ACCESS_SECRET='<secret>'
S3_PUBLIC_URL='https://cdn.example.com'

NOTIF_SERVER='https://forum.example.com'

改完重启 web/celery/piefednotifs 三进程，跑一遍 flask config_check 确认全绿（除联邦域名告警消失外）。

六、FAQ

1. 改了 .env.docker 不生效？ compose 的 env_file 在进程环境注入，需 docker compose up -d 重建（restart 不会重读文件）。用 flask config_check 核对实际值。
2. config_check 的 ❌ 与 ⚠️ 怎么分级？ 官方口径：✅ 通过、⚠️ 可容忍（如无邮件）、❌ 必须修复才能上线（实测本机 2 条 ⚠️ 均为测试形态预期）。
3. MAIL_USE_TLS 设 False 仍走 TLS？ 见 4.5：该键"存在即开"，删行才是关。
4. 中文乱码/emoji 报错？ init-db 已校验 UTF8；若绕过校验（裸机自建库），按官方提示 createdb -E UTF8 -T template0 重建并迁移。
5. 想全关注册但留邀请？ 面板侧 openRegistrations 关（nodeinfo 实测 false），配合"approve registrations" 角色权限审批。
6. Redis 被 OOM 杀？ 优先调低 REDIS_MEMORY_LIMIT 与 Celery 并发，再考虑给 Redis 设 maxmemory；联邦暂停机制（4.4）就是为此设计。

七、参考链接

• 配置源码：config.py、gunicorn.conf.py、env.sample、env.docker.sample（https://codeberg.org/rimu/pyfedi ，v1.8.10）
• 官方安装文档：https://join.piefed.social/docs/installation/ ；INSTALL-docker.md / INSTALL.md
• S3 实践：仓库 docs/Using Backblaze B2 with PieFed.md、docs/Using Wasabi S3 with Piefed.md
• 站内配套：《PieFed 1.8.10 Docker Compose 部署指南》、《PieFed 1.8.10 常用 CLI 命令与工具详解》、《Lemmy 0.19.21 配置参数详解》