环境配置

.env.example

占位值统一写 replace-me，这样它既不会被当成真值，也不会被密钥扫描误报。必填项在注释里标出来。

# 复制为 .env 后填写。本文件只有占位值，任何真实密钥都不要写进来。
# SESSION_SECRET 必填。生成：openssl rand -base64 32
# DB_PASSWORD 必填。测试库连接串 TEST_MYSQL_DSN 未设置时相关测试跳过。
SESSION_SECRET=replace-me
DB_PASSWORD=replace-me
API_KEY=replace-me
TEST_MYSQL_DSN=replace-me
WEB_PORT=8080

compose 中的引用

必填密钥写 ${VAR:?说明}，未设置时 Compose 在启动前失败。不要给 SESSION_SECRET 写 :-某段口令，否则漏配时会安静地使用默认密钥。端口这类可以有公开默认值的项才用 ${WEB_PORT:-8080}。

services:
  api:
    environment:
      SESSION_SECRET: ${SESSION_SECRET:?SESSION_SECRET is required}
      DB_PASSWORD: ${DB_PASSWORD:?DB_PASSWORD is required}
    ports:
      - "${WEB_PORT:-8080}:8000"

.gitignore 与 .dockerignore

用 .env* 覆盖所有变体（.env.local、.env.production），再单独放行示例文件。.dockerignore 里的同一行决定镜像里有没有这份文件。

# .gitignore
.env*
!.env.example

# .dockerignore
.env*

密钥泄漏之后按顺序做四件事

顺序不能换：先让旧密钥失效，再清理历史。只清理历史而不轮换，等于把还在生效的凭据继续留在别人的克隆里。

1. 生成新值并更新部署环境与本机 .env
   openssl rand -base64 32

2. 在签发方作废旧值（数据库改密码、控制台删除 API Key）

3. 从历史里移除该文件（这一步之后所有协作者需要重新克隆）
   git filter-repo --path .env.example --invert-paths

4. 确认同类字符串以后会被拦住
   gitleaks detect --no-banner --redact

.gitleaks.toml（补一条针对本项目会话密钥的规则）

不要把 .env.example 加进忽略名单——第一件事故正是发生在那个文件里。字段名以官方文档为准。

# 默认规则已覆盖常见密钥前缀，这里补一条本项目专用的模式。
[extend]
useDefault = true

[[rules]]
id = "project-session-secret"
description = "会话密钥不得写进任何被跟踪的文件"
regex = '''SESSION_SECRET\s*=\s*[A-Za-z0-9+/=]{16,}'''

第一套：插值，从高到低

1. shell 中已经 export 的变量
2. --env-file 指定的文件
3. 项目目录里的 .env

第二套：容器内的环境变量，从高到低

1. docker compose run -e
2. 带插值的 environment 或 env_file
3. Compose 文件里写死的 environment
4. env_file 里的值
5. 镜像的 ENV

出错时按顺序跑这三条

第一条判断是不是 shell 覆盖，第二条看插值之后的真实结果，第三条看容器里到底有没有这个变量。

env | grep SESSION_SECRET
docker compose config
docker compose exec api printenv | grep SESSION_SECRET

助手交出来的样子

# .env.example
DB_PASSWORD=<这里本该是占位符>
API_KEY=<这里本该是占位符>

# 新增一个变量时
.env        PORT=8081         ← 改了
config      PORT=8080         ← 没改