配置、凭据与安全边界
解释后端配置校验、Nuxt 代理、生产密钥、Session 与 MFA 的真实行为及排查顺序。
配置归属
开发配置来自根目录 .env.example；生产模板以 deploy/env.production.example 为主。根目录 Makefile 会载入 .env，生产脚本通过 PROD_ENV_FILE 指定私有配置。不要把开发配置文件直接带到生产主机，也不要通过打印全部环境变量来排查连接问题。
本章依据 server/internal/config/config.go、web/nuxt.config.ts 和部署脚本。修改配置前记录变量名、用途和旧值的安全保存位置，不在工单中记录密钥明文。
后端必需项
DATABASE_URL 必须存在。REDIS_URL 使用 redis 或 rediss 协议，默认指向本机 Redis。APP_ENV 只接受 development、test 或 production；HTTP_ADDRESS 默认 :8080，SHUTDOWN_TIMEOUT 默认 10s。
生产模式要求 HTTPS PUBLIC_BASE_URL、非空且格式合法的 TRUSTED_PROXY_CIDRS，以及至少 32 字符的 SESSION_SIGNING_KEY、MFA_ENCRYPTION_KEY、CSRF_SECRET。应用的长度校验不代表密钥足够随机，发布预检还会拦截模板占位值。可信代理范围应根据实际部署收窄，不能照抄为信任所有来源。
前端地址的区别
NUXT_API_ORIGIN 是 Nuxt 服务端代理到 Go API 的内部地址；NUXT_PUBLIC_API_BASE 默认 /api/v1；NUXT_PUBLIC_SITE_URL 用于公开站点 URL。API 内部地址与对外域名不是同一个概念，浏览器也不应直接使用 Compose 内部服务名。
本地避让 API 端口的示例：
NUXT_API_ORIGIN=http://127.0.0.1:8081 make web-dev生产 Web 容器应访问服务名 api:8080。修改 canonical 站点域名后要检查真实公开页面与 sitemap，不能只验证首页能打开。
管理员与会话
生产没有内置管理员。初始化需要 ADMIN_USERNAME、ADMIN_PASSWORD、ADMIN_DISPLAY_NAME 和有效角色，密码长度为 12–256 字符。管理员可在 /admin/security 完成 TOTP 绑定验证；仅生成密钥并不等于启用 MFA。
认证使用 Cookie Session，后台写请求还需要与会话绑定的 X-CSRF-Token。ADMIN_SESSION_TTL 默认为 8h，必须大于零且不超过 24h。不要将长期令牌存进 LocalStorage，也不要把会话 Cookie 或 TOTP 秘钥放进内容包。
账号初始化和日常编辑应区分权限职责。编辑者缺少发布权限时由有权限的负责人完成发布，不通过共享超级管理员密码绕过控制。排查登录问题可记录账号标识、时间和请求编号，但应遮蔽请求中的密码和验证码。
验证和故障判定
curl --fail-with-body http://127.0.0.1:8080/health/ready
make verify-prod-operator后一命令验证发布操作脚本，不替代真实生产配置预检。Redis 不可用时 API 可继续启动、公开内容回源数据库，ready 可返回 200 且 degraded=true；此时应单独检查登录、验证码和限流能力，不能宣称整体服务正常。
变更停止与恢复
启动提示缺少生产密钥、URL 非 HTTPS 或代理 CIDR 不合法时，停止发布并修正对应配置。密钥轮换应先明确旧会话和已绑定 MFA 数据的兼容策略，特别不能随意替换加密密钥后期待旧数据仍可解密。配置回退恢复的是已知正确的配置，不是恢复泄露的密钥；发生泄露需走受控轮换。