Baby Buddy 配置参数详解

‍‍​​‌​> 本文基于 v2.11.0 真机逐项实测：每个参数都给出「配置 → 重启 → 验证 → 回显」的完整闭环。安装与进程托管背景见 《Baby Buddy 安装部署指南（Ubuntu 22.04 直装实录）》，命令行工具见 《Baby Buddy 常用 CLI 命令详解》。

一、配置加载机制：一个 .env 打天下

Baby Buddy 不提供 config 文件，配置完全走环境变量，由 python-dotenv 在 settings 加载时执行 load_dotenv(find_dotenv()) 自动查找 .env（从工作目录向上逐级找）。因此：

• systemd 单元里 WorkingDirectory=/opt/babybuddy/app + 应用目录下的 .env 即可生效，无需在 unit 里写 EnvironmentFile；
• 改 .env 后必须重启进程（gunicorn 启动时一次性读入），不重启不生效——这是本文多项实测反复验证的铁律；
• 带 DATABASE_URL 时走 dj-database-url 单变量模式，否则走 DB_* 分量模式（两套互斥，见 3.2）。

全部配置在 babybuddy/settings/base.py（v2.11.0 共 412 行）集中定义。下面按「身份与安全 → 数据库 → 时区与语言 → 邮件 → 存储与路径 → 登录防护 → 分组与集成」逐项实测。

二、身份与安全类

2.1 SECRET_KEY（必配）

Django 加密签名根密钥。缺省时 SECRET_KEY = None，启动直接崩。生成方法：

python3 -c "import secrets; print(secrets.token_urlsafe(48))"

密钥泄露 = 会话伪造风险。轮换密钥会使现有 session/密码重置链接全部失效，属预期行为。

2.2 DEBUG（生产必 False）

DEBUG=False   # 默认 False；True 会暴露详细错误页与配置

DEBUG=True 时 Django 静态服务接管 + 错误页泄密，生产禁开。该值经 strtobool() 解析，接受 y/yes/t/true/on/1 与 n/no/f/false/off/0，写 True（首字母大写）也能正确解析为真，但写 1、true 更稳。

2.3 ALLOWED_HOSTS（必实测项）

逗号分隔的合法 Host 列表，* 表示不限制。收紧型对照实验（改配置 → 重启 → 双 Host 验证）：

sed -i "s/^ALLOWED_HOSTS=.*/ALLOWED_HOSTS=babybuddy.example.com/" .env
systemctl restart babybuddy
curl -s -o /dev/null -w "Host=evil.com -> %{http_code}\n" -H "Host: evil.com" http://127.0.0.1:80/login/
curl -s -o /dev/null -w "Host=proper -> %{http_code}\n" -H "Host: babybuddy.example.com" http://127.0.0.1:80/login/

实测回显：

Host=evil.com -> 400
Host=proper -> 200

默认 ALLOWED_HOSTS=* 时任意 Host 均放行（实测 Host=evil.com 返回 200）。生产务必收敛为具体域名；走 Nginx 时 Nginx 的 server_name 是第一道闸，这里的是应用层第二道。

2.4 CSRF / Session 安全三件套

配套服务端常量（不可配，实查 base.py）：SESSION_COOKIE_HTTPONLY=True、CSRF_COOKIE_HTTPONLY=True；反代终止 TLS 时设 SECURE_PROXY_SSL_HEADER=on（任意非空值即可触发 ("HTTP_X_FORWARDED_PROTO", "https")）。

2.5 REVERSE_PROXY_AUTH（反代 SSO 接入）

默认 False。开启后追加 CustomRemoteUser 中间件与 RemoteUserBackend，由上游反代（Authelia、Authentik 等）认证后传 REMOTE_USER 头直登。验证方式：

grep -c "CustomRemoteUser" /opt/babybuddy/app/babybuddy/settings/base.py
# 配置前进程内可见性由条件分支控制；开启后重启，日志无异常且登录页自动跳过

开启此模式后应用自身登录页不再校验密码，必须确保反代对 /login/ 的保护，否则等于裸奔。

三、数据库类

3.1 DB_* 分量模式（默认推荐）

切换实测（SQLite → PostgreSQL 完整闭环）：

cat >> .env <<'EOF'
DB_ENGINE=django.db.backends.postgresql
DB_NAME=babybuddy
DB_USER=babybuddy
DB_PASSWORD=q1w2e3r4
DB_HOST=127.0.0.1
DB_PORT=5432
EOF
systemctl restart babybuddy
su -s /bin/bash babybuddy -c "cd /opt/babybuddy/app && venv/bin/python manage.py migrate --noinput"

migrate 尾部实测回显：

  Applying core.0037_alter_diaperchange_color... OK
  Applying core.0038_tummytime_notes... OK
  Applying sessions.0001_initial... OK

迁移完成后表归属验证：

echo "\dt core_child" | su -s /bin/bash babybuddy -c "cd /opt/babybuddy/app && venv/bin/python manage.py dbshell"

实测回显：

            List of relations
 Schema |    Name    | Type  |   Owner
--------+------------+-------+-----------
 public | core_child | table | babybuddy
(1 row)

3.2 DATABASE_URL 单变量模式

设置任一 DATABASE_URL 环境变量后，DB_* 全部失效（if/else 互斥分支），格式：

DATABASE_URL=postgres://babybuddy:q1w2e3r4@127.0.0.1:5432/babybuddy

两套并存时优先级：DATABASE_URL > DB_*。编排部署场景常用单变量，直装场景建议分量模式（密码含特殊字符时无需 URL 编码）。

3.3 缓存（无独立 env，默认走库）

v2.11.0 默认 DatabaseCache（表 cache_default），无需 Redis。迁移后若缓存表缺失会报错，执行一次 manage.py createcachetable 即可（migrate 通常已自动建）。

四、时区与语言

4.1 TZ（系统时区）与 TIME_ZONE（Django 时区）的区别——高频误区

实测结论，先看代码事实：

grep -n "^TIME_ZONE" /opt/babybuddy/app/babybuddy/settings/base.py

实测回显：

TIME_ZONE = "UTC"

再在运行进程里验证（UTC now 与 localtime 一致）：

TIME_ZONE = UTC
utc now: 2026-10-28 04:10:46.939705+00:00
local now: 2026-10-28 04:10:46.939714+00:00

三处时区各管各的：

即：数据库里所有时间都是 UTC（回显中的 Z 后缀），显示层的偏移由用户级时区决定。想让全家手机显示一致，去每账号的个人设置里选 Asia/Shanghai，而不是改 .env。

4.2 LANGUAGE_CODE 与界面语言

站点默认语言 LANGUAGE_CODE = "en-US"（settings 硬编码），可用值来自 LANGUAGES 列表（含 zh-hans 简体中文、zh-hant/zh-tw 繁体、日/韩/德/法等 28 种）。语言包实测——用 Accept-Language: zh-hans 请求登录页：

curl -s -H 'Accept-Language: zh-hans' http://127.0.0.1:80/login/ | grep -oP '(用户名|密码)' | sort -u

实测回显（中文渲染正常，无需额外安装）：

密码
用户名

两种改法：

1. 站点级：LANGUAGE_CODE 在 settings 里硬编码，改它需要覆写 settings（生产不建议）；locale 目录在 locale/，compilemessages 后生效；
2. 用户级（推荐）：每用户在界面 Settings 里自选语言（UserLanguageMiddleware 注入），多 caregiver 家庭各自中文/英文互不影响。

五、邮件类

默认 EMAIL_BACKEND = django.core.mail.backends.console（邮件打日志，适合单机自用）。配了 EMAIL_HOST 即自动切 SMTP：

console 后端实测（不改任何配置直接发测试邮件，内容打到 stdout）：

su -s /bin/bash babybuddy -c "cd /opt/babybuddy/app && venv/bin/python manage.py sendtestemail admin@example.com"

实测回显：

Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: Test email from babybuddy-server on 2026-10-28 04:10:16.822340+00:00
From: webmaster@localhost
To: admin@example.com
Date: Wed, 28 Oct 2026 04:10:16 -0000
Message-ID: <179316061682.8409.9630026461217708665@babybuddy-server>

If you're reading this, it was successful.

From: webmaster@localhost 与 subject 里的主机名证明走的 console 后端；切 SMTP 后重新执行同命令，真实投递成功无输出即成功（退出码 0）。

六、存储与路径

6.1 SUB_PATH（子路径部署）

默认空。设 SUB_PATH=/baby 后应用挂到 http://host/baby/ 下（STATIC_URL 自动拼接），适合与其他服务共用域名。必须在首次部署前确定——迁移后改子路径需要重跑 collectstatic。

6.2 MEDIA 与 S3（可选）

• 本地模式：MEDIA_ROOT = BASE_DIR/media（自动），Nginx location /media/ 直出；
• 对象存储模式：设 AWS_STORAGE_BUCKET_NAME（必填）+ AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY + AWS_S3_ENDPOINT_URL（MinIO 自建必填），媒体存储自动切换为 storages.backends.s3boto3.S3Boto3Storage。适合多副本部署共享儿童照片。

6.3 静态资源（不可配，理解即可）

STORAGES["staticfiles"] 固定为 Whitenoise CompressedManifestStaticFilesStorage：collectstatic 时生成带哈希文件名 + gzip 预压缩 + manifest 清单，这就是实测回显里 446 post-processed 的含义。WHITENOISE_ROOT 指向 static/babybuddy/root（PWA manifest 与图标直出根路径）。

七、登录防护（django-axes）

锁定实测（连续错误登录，第 5 次 429）：

try1: 200
try2: 200
try3: 200
try4: 200
try5: 429

锁定后即使密码正确也 429（实测 locked-login: 429），锁定页标题与文案：

403 Too Many Login Attempts
| Baby Buddy

Account locked: too many login attempts. Please try again later.

解锁三连（按场景选用，完整实测见 CLI 篇）：

manage.py axes_reset_username admin   # 按用户名解锁（回显 1 attempts removed.）
manage.py axes_reset_ip 10.89.71.1    # 按 IP 解锁
manage.py axes_reset                  # 全量清空

八、分组与集成类

8.1 BABY_BUDDY 三参

BABY_BUDDY = {
    "ALLOW_UPLOADS": True,        # env ALLOW_UPLOADS，默认 True；False 禁止上传照片
    "READ_ONLY_GROUP_NAME": "read_only",   # 只读组成员仅可看
    "CAREGIVER_GROUP_NAME": "caregiver",   # 照护者组可记录数据
}

权限模型：admin 建组 → 把用户拉进 caregiver（可录入喂养/睡眠等）或 read_only（只能看报表）→ API 同样按 Django Model 权限过滤（BabyBuddyDjangoModelPermissions）。多 caregiver 家庭的核心玩法。

8.2 ENABLE_HOME_ASSISTANT_SUPPORT

默认 False。开启后允许 Home Assistant 以 long-lived token 头 Authorization: Bearer <token> 调 API（绕过 Django session/CSRF 流程）。配合 HA 的 RESTful sensor 记录喂养计时器。

8.3 ROLLING_SESSION_REFRESH

默认 86400（秒）：RollingSessionMiddleware 每隔该时长重置会话 ID，防会话固定。家庭内网可不动。

九、REST API 相关（只读理解）

• 认证：Session + Token 双通道（api.authentication.TokenAuthentication），token 由 manage.py drf_create_token <user> 签发；
• 分页：LimitOffset，PAGE_SIZE=100；
• 过滤：django-filter + OrderingFilter 全局启用；
• Schema：OpenAPI 3，manage.py generateschema 导出（v2.11.0 源码已带 openapi-schema.yml）。

API 实操与 curl 示例全部在 《Baby Buddy 常用 CLI 命令详解》。

十、参数速查表

所有「默认」列均实查自 v2.11.0 settings/base.py（412 行）与本文真机验证。改任何变量后：systemctl restart babybuddy 才生效；验证三板斧——curl 行为、manage.py shell 打印、日志回显。