social-app/docs/plans/PLAN-env-config-refactor-2026-02-05.md

# Plan: Env Config Refactor

**Date:** 2026-02-05
**Author:** AI Assistant
**Status:** Draft

## Overview

对 `.env` / `.env.example` 与 `backend/src/core/config/settings.py` 做一次一致性重构，消除同一含义的重复配置来源（例如 `DATABASE_URL` 与分段口令、host/port 与完整 URL）。目标是明确一组规范化环境变量，确保后端仅通过 Settings 读取，并兼顾 `infra/docker/docker-compose.yml` 的现有依赖。

## Requirements

### Functional
- [ ] 提出“规范化环境变量”清单（canonical set），覆盖后端与 Supabase 本地栈的关键配置。
- [ ] 定义 Settings 的读取与推导策略（优先级、默认值、派生字段）。
- [ ] 给出 `.env` / `.env.example` 的迁移步骤与兼容策略。
- [ ] 兼容 `infra/docker/docker-compose.yml` 使用的变量（保证 compose 不被破坏）。

### Non-Functional
- [ ] Performance: Settings 解析不增加明显启动耗时
- [ ] Security: 不在仓库中暴露真实密钥；对后端使用的数据库 URL 与密钥来源保持单一可信源

## Technical Approach

以“后端设置单一来源 + docker-compose 继续使用 Supabase 变量”为原则：
- 后端只接受 `SOCIAL_DATABASE_URL` 与必要的 Supabase 访问变量（`public_url/anon_key/service_role_key/jwt_secret`）。
- Supabase stack 继续使用 `SOCIAL_SUPABASE__*` 变量，保持 compose 模板稳定。
- 通过 Settings 做派生字段（例如 `supabase.url`）与兼容性读入（可选旧字段，设置弃用期）。

### Key Decisions
| Decision | Rationale |
|----------|-----------|
| 保留 `SOCIAL_DATABASE_URL` 作为后端唯一数据库连接来源 | 避免与分段 `POSTGRES_*` 产生冲突，清晰配置入口 |
| Supabase stack 变量继续使用 `SOCIAL_SUPABASE__*` | docker-compose 已广泛引用，改动成本高 |
| Settings 允许短期兼容旧字段 | 保障迁移期间部署安全，减少切换风险 |

## Implementation Steps

### Phase 1: Inventory & Mapping (2 hours)
1. 盘点 `.env` / `.env.example` 与 `settings.py` 的变量差异，标注重复与冲突字段。
2. 输出 canonical env vars 列表与映射关系表（旧 -> 新）。

### Phase 2: Settings Refactor (3 hours)
1. 在 `settings.py` 中实现新的读取优先级与派生字段。
2. 为旧字段加兼容读取与弃用注记（仅内存兼容，不继续写入）。

### Phase 3: Env Templates Update (2 hours)
1. 更新 `.env.example` 为 canonical 变量，并标注“后端使用/compose 使用”。
2. 更新 `.env`（本地开发用）以匹配新模板。

### Phase 4: Validation & Docs (2 hours)
1. 本地启动 docker-compose，验证 Supabase stack 与后端连接正常。
2. 写简要迁移说明（README 或 docs/ 中短节）。

## Files to Modify

| File | Changes |
|------|---------|
| `.env.example` | 替换为 canonical 变量，移除重复字段 |
| `.env` | 与模板对齐，移除重复字段 |
| `backend/src/core/config/settings.py` | 调整 Settings 读取与派生策略 |
| `infra/docker/docker-compose.yml` | 仅在必要时新增兼容映射变量 |
| `README.md` 或 `docs/*` | 增加迁移说明 |

## Files to Create

| File | Purpose |
|------|---------|
| `docs/plans/PLAN-env-config-refactor-2026-02-05.md` | 规划文档 |

## Dependencies

- [ ] 无新增第三方依赖

## Proposed Canonical Env Vars

### Backend (Settings)
- `SOCIAL_DATABASE_URL` (required) — 后端数据库连接（唯一来源）
- `SOCIAL_SUPABASE__PUBLIC_URL` — Supabase 公网/本地外部访问 URL
- `SOCIAL_SUPABASE__API_EXTERNAL_URL` — Supabase Auth 回调外部 URL
- `SOCIAL_SUPABASE__ANON_KEY` — 前端/匿名访问 key
- `SOCIAL_SUPABASE__SERVICE_ROLE_KEY` — 后端服务角色 key
- `SOCIAL_SUPABASE__JWT_SECRET` — JWT 验证密钥（后端验证用）

### Supabase Stack (docker-compose)
- `SOCIAL_SUPABASE__POSTGRES_HOST`
- `SOCIAL_SUPABASE__POSTGRES_PORT`
- `SOCIAL_SUPABASE__POSTGRES_DB`
- `SOCIAL_SUPABASE__POSTGRES_PASSWORD`
- `SOCIAL_SUPABASE__KONG_HTTP_PORT`
- `SOCIAL_SUPABASE__KONG_HTTPS_PORT`
- `SOCIAL_SUPABASE__SITE_URL`
- `SOCIAL_SUPABASE__JWT_SECRET`
- `SOCIAL_SUPABASE__ANON_KEY`
- `SOCIAL_SUPABASE__SERVICE_ROLE_KEY`
- 其余 `SOCIAL_SUPABASE__*` 保持现状（Logflare、SMTP、Pooler 等）

## Mapping Strategy

1. **Backend DB**
   - Only: `SOCIAL_DATABASE_URL`
   - Deprecated: `SOCIAL_SUPABASE__POSTGRES_*`（后端不再拼接）

2. **Supabase URL**
   - Primary: `SOCIAL_SUPABASE__PUBLIC_URL`
   - Fallback: `SOCIAL_SUPABASE__API_EXTERNAL_URL`
   - Settings 中 `supabase.url` 由上述字段派生

3. **Docker Compose**
   - 继续读 `SOCIAL_SUPABASE__POSTGRES_*`
   - 不引入 `SOCIAL_DATABASE_URL` 到 compose，以免混淆职责

## Migration Steps

1. 在 `settings.py` 中增加兼容逻辑：若 `SOCIAL_DATABASE_URL` 不存在，可临时从 `SOCIAL_SUPABASE__POSTGRES_*` 组装（同时记录弃用）。
2. 更新 `.env.example`：只保留 canonical 变量并标注用途。
3. 更新 `.env`：移除重复字段，确保本地后端使用 `SOCIAL_DATABASE_URL`。
4. 校验 compose：`infra/docker/docker-compose.yml` 不依赖被移除字段。
5. 发布说明：提示下游用户迁移并在下个版本移除兼容逻辑。

## Testing Strategy

- **Unit Tests:** Settings 派生字段与优先级规则
- **Integration Tests:** 后端连接 Supabase DB（使用 `SOCIAL_DATABASE_URL`）
- **E2E Tests:** 关键登录/读写流程（确认 JWT 与 Service Role 配置无误）

## Risks & Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| compose 变量被误删导致 Supabase 启动失败 | High | Medium | 迁移前后对照 `docker-compose.yml`，保留全部 `SOCIAL_SUPABASE__*` 依赖 |
| 后端数据库连接断开 | High | Medium | 兼容旧字段，先引入新变量再切换 |
| 开发环境 `.env` 未更新 | Medium | High | 更新模板并在 README 明确迁移步骤 |

## Estimated Effort

| Phase | Effort |
|-------|--------|
| Phase 1 | 2 hours |
| Phase 2 | 3 hours |
| Phase 3 | 2 hours |
| Phase 4 | 2 hours |
| **Total** | **9 hours** |