Socialhome 0.24.0 配置参数详解

目标：把 Socialhome 0.24.0 后端的全部环境变量配置逐项讲清——默认值、作用、什么时候必须动它。依据三层交叉：官方 running 文档 Configuration 一节（默认值权威）、后端 settings 源码（config/settings/common.py 735 行 / production.py 153 行）、以及 2026-11-02 在真实运行实例上的实测行为（含故意触发的报错原文）。部署上下文见 《Socialhome 0.24.0 Docker Compose 部署指南》。

一、配置机制：一个 .env 文件驱动全部

Socialhome 的配置面只有环境变量一个入口。官方 running 文档原文：「Configuration mainly happens through environment variables. Those are passed to Django via the file .env in the repository root.」settings 源码里每个可调项都写成 env("变量名", default=...) 的形式，加载顺序：

1. 进程启动时读取环境（裸机从仓库根 .env；容器路线由编排的 env_file 注入）；
2. DJANGO_SETTINGS_MODULE 决定装配哪套 settings（生产用 config.settings.production，它继承 common.py 再叠加安全项）；
3. 改完配置需要重启应用进程才生效（裸机官方口径 sudo service socialhome restart；编排环境即重建后端服务单元）。

三个机制级注意点（均为实测）：

• No .env file found! 告警无害：后端制品启动时每个进程都会刷 UserWarning: !!! No .env file found!（settings 源码 common.py:32 行）——它期望 /app/.env 物理存在，用 env_file 注入时该告警必然出现，不影响任何功能；
• REDIS_URL 已废弃且会直接起不来（实测报错原文见第八章）；
• 官方仓库根的 env.example 是开发机模板（DJANGO_SETTINGS_MODULE=config.settings.local），生产别照抄，按官方 Docker 页最小集来。

二、必配项（官方 Docker 页最小集）

官方文档 Docker 安装页「Backend configuration」列出的必改清单，加上数据库口令共五项：

三、HTTPS 与安全响应头

官方 Docker 页同时要求：TLS 必须在 LB 终结，且 LB 要向后端回写 X-Forwarded-Proto: https——后端据此判断协议，不要在应用层再堆证书。

四、注册与实例治理

💡 说明：治理面就这一张表——没有域联邦封禁、举报工作流之类的变量，公共大实例运营者请对照 《Mastodon 4.7.3 配置参数详解》 评估差距（选型结论见 《Socialhome 0.24.0 介绍与选型指南》 第六章）。

五、邮件：注册的硬依赖

官方 running 文档语气非常明确：「Note, email is required for signing up. Users will not be able to sign up if the instance does not have working email sending.」

没有可用邮件服务时，初始管理员请按官方 shell 流程建号并用 EmailAddress.objects.filter(...).update(verified=True) 跳过邮件确认（部署篇第九节实测）。

六、联邦身份与匿名可见性

七、Redis 与进程伸缩（资源大头）

实测进程行原文（/proc 核对，见部署篇第十节）：

/usr/local/bin/python3.12 /usr/local/bin/dramatiq --path . --processes 6 --threads 8 --worker-shutdown-timeout 600000 django_dramatiq.setup django_dramatiq.tasks socialhome.tasks.apps ...

Circus 进程守护配置按 $(circus.env.daphne_worker_num)、$(circus.env.rqworker_num) 读取上述变量展开进程组，并给每个 worker 设了 rlimit_as 1.6GB 的内存上限保护。

八、实测：REDIS_URL 是配置雷区

历史版本曾支持 REDIS_URL 单串配置，现行版本改为检测到即拒绝启动。实测在 REDIS_URL 注入后执行任何 manage 命令：

  File "/app/config/settings/production.py", line 82, in <module>
    raise ImproperlyConfigured("Setting REDIS_URL as an environment variable has been removed. Please define "
django.core.exceptions.ImproperlyConfigured: Setting REDIS_URL as an environment variable has been removed. Please define REDIS_HOST, REDIS_PORT, REDIS_DB and/or REDIS_PASSWORD. See docs for the defaults.

从旧版升级或抄了老教程的部署，务必把 REDIS_URL 拆成四件套。

九、日志与监控

裸机还有第二份日志：Circus 进程日志（Upstart 系统在 /var/log/upstart/socialhome-circus.log），Daphne/worker 起不来先看它；应用日志（LOG_TARGET 所指）用来看联邦投递错误——官方 running 文档「Log files」一节的分工。

十、性能与缓存调优

时间线预缓存（Redis 占用直接相关）：

AP 回复集合回刷（忙碌实例的资源大户）：

十一、语言与时间

十二、扩展钩子：把 Django 生态接进来

这三项让 Socialhome 本质上是「一个可挂载任意 Django app 的联邦平台」，二次开发友好度是它对比 BEAM/Go 系的最大配置优势。

十三、Matrix 集成（alpha，勿用于生产）

官方 running 文档自述「Note! Extremely alpha, work on progress, non-functional」。方向与 Diaspora/AP 不同：Socialhome 不做 Matrix homeserver，而是做「多人客户端」，需额外部署一套专用的 Dendrite（仅 0.3.11 实测过），假定 homeserver 域名是 matrix.<SOCIALHOME_DOMAIN>:443，well-known 委托由 Socialhome 自动生成。相关变量（settings 源码实查）：

十四、生效方式与变更纪律

• 改 .env/env_file 后：裸机 sudo service socialhome restart；编排环境重建后端服务单元（本文环境 docker compose up -d --force-recreate backend），Circus 会按新变量重新展开 daphne/rqworker/dramatiq 进程组；
• DJANGO_SECRET_KEY 永不再改；SOCIALHOME_DOMAIN/DJANGO_ALLOWED_HOSTS 决定联邦身份，实例开放联邦后不可安全变更；
• 备份口径（官方 running 文档四件套）：数据库、.env、socialhome/media/ 上传目录、Redis 数据——与部署篇持久化卷一一对应。

十五、小结与关联

Socialhome 的配置面可以一句话说完：必配五项定身份，邮件配置定生死，进程四件套定资源，其余默认即可跑。本文表格默认值全部对齐官方 running 文档 Configuration 一节（查询日期 2026-11-02），报错与进程行为为当日实例实测。

• 部署落地与持久化卷：《Socialhome 0.24.0 Docker Compose 部署指南》；
• 配置改完后的验证与运维命令（迁移、搜索索引重建、队列巡检）：见 《Socialhome 0.24.0 常用 CLI 命令与工具详解》；
• 为什么选它、边界在哪：《Socialhome 0.24.0 介绍与选型指南》。