qzl
204 lines
5.3 KiB
Markdown
204 lines
5.3 KiB
Markdown
# 配置规则与使用原则
|
||
|
||
## 配置文件组织
|
||
|
||
### 1. 环境变量规范（真相源）
|
||
|
||
**文件位置**：`configs/env/.env.example`
|
||
|
||
**作用**：
|
||
- 定义应用层环境变量的名称、类型、用途和敏感级别
|
||
- 作为应用配置的"真相源"（source of truth）
|
||
- 不可直接用于运行，仅作为参考和规范
|
||
- Docker/Supabase 栈配置不在本文件，使用 `infra/local/env/.env.example`
|
||
- 本文件仅包含应用层连接配置（如 `SUPABASE_URL`、`DATABASE_URL`），不包含 Supabase 栈运行变量
|
||
- 不得在 `infra/local/env/.env.example` 中添加应用层变量（如 `PUBLIC_`、`API_`）
|
||
|
||
**变量分类**：
|
||
- `public`：可公开的信息，如服务地址、端口号
|
||
- `secret`：敏感信息，如密钥、密码、连接串
|
||
|
||
**变量块说明**：
|
||
- A. 通用环境（APP_ENV、LOG_LEVEL、TZ）
|
||
- B. Flutter 配置（仅 PUBLIC_ 变量）
|
||
- C. FastAPI 服务配置
|
||
- D. Supabase / Postgres 连接配置
|
||
- E. Redis 配置
|
||
- F. Milvus 配置
|
||
- G. 对象存储配置（可选）
|
||
- H. 其他配置
|
||
|
||
### 2. 本地开发配置
|
||
|
||
**文件位置**：`configs/env/.env`
|
||
|
||
**作用**：
|
||
- 本地应用层的实际配置文件
|
||
- 从 `configs/env/.env.example` 复制后填入真实值
|
||
- **禁止提交到 Git 仓库**
|
||
|
||
**创建方式**：
|
||
```bash
|
||
cp configs/env/.env.example configs/env/.env
|
||
# 编辑 configs/env/.env，填入实际值
|
||
```
|
||
|
||
### 3. 本地 Supabase 栈配置
|
||
|
||
**文件位置**：`infra/local/env/.env`
|
||
|
||
**作用**：
|
||
- 本地 Supabase + 周边依赖的实际配置文件
|
||
- 从 `infra/local/env/.env.example` 复制后填入真实值
|
||
- **禁止提交到 Git 仓库**
|
||
|
||
**创建方式**：
|
||
```bash
|
||
cp infra/local/env/.env.example infra/local/env/.env
|
||
```
|
||
|
||
### 4. 云端部署配置
|
||
|
||
**方式一：环境文件**
|
||
- 文件位置：`infra/cloud/volcano/env/.env`（不提交）
|
||
- 从 `infra/cloud/volcano/env/.env.example` 复制后填入云端真实值
|
||
- 仅用于本地测试云端连接
|
||
|
||
**方式二：Secret 注入（推荐）**
|
||
- 使用火山云或其他云平台的 Secret 管理服务
|
||
- 通过 CI/CD 或容器运行时注入环境变量
|
||
- 代码无需修改，通过环境切换
|
||
|
||
### 5. 应用特定配置
|
||
|
||
**Flutter 配置**：
|
||
- `configs/flutter/dev.json` —— 开发环境
|
||
- `configs/flutter/prod.json` —— 生产环境
|
||
- 通过 `--dart-define` 在构建时注入
|
||
|
||
## 安全原则
|
||
|
||
### Public vs Secret
|
||
|
||
**Public 变量**：
|
||
- 可公开的服务地址和端口号
|
||
- 前端可直接使用的配置
|
||
- 示例：`PUBLIC_API_BASE_URL`、`API_PORT`
|
||
|
||
**Secret 变量**：
|
||
- 密钥、密码、连接串
|
||
- 仅服务端使用的敏感信息
|
||
- 示例：`DATABASE_URL`、`REDIS_URL`、`JWT_SECRET`
|
||
|
||
### Flutter 配置限制
|
||
|
||
**严格规则**：
|
||
- Flutter 只能使用以 `PUBLIC_` 开头的变量
|
||
- 严禁将任何 secret 信息注入到 Flutter
|
||
- 通过 `--dart-define` 在构建时注入，运行时不可修改
|
||
|
||
**示例**：
|
||
```bash
|
||
# ✅ 正确：Flutter 使用 PUBLIC_ 变量
|
||
flutter run --dart-define=PUBLIC_API_BASE_URL=http://localhost:8000
|
||
|
||
# ❌ 错误：Flutter 不能使用 secret
|
||
flutter run --dart-define=DATABASE_URL=postgresql://user:pass@localhost/db
|
||
```
|
||
|
||
### 后端配置读取
|
||
|
||
**严格规则**：
|
||
- `apps/api` 和 `apps/worker` 只能通过环境变量读取配置
|
||
- 不得直接读取 `infra/local/*.env` 文件路径
|
||
- 使用 Python 的 `os.getenv()` 或环境变量库
|
||
|
||
**示例**：
|
||
```python
|
||
# ✅ 正确：通过环境变量读取
|
||
import os
|
||
|
||
database_url = os.getenv("DATABASE_URL")
|
||
|
||
# ❌ 错误：直接读取本地配置文件
|
||
from dotenv import load_dotenv
|
||
load_dotenv("configs/env/.env") # 禁止
|
||
```
|
||
|
||
## 使用方式
|
||
|
||
### 1. 本地开发
|
||
|
||
1. 复制环境变量模板：
|
||
```bash
|
||
make env
|
||
```
|
||
|
||
2. 启动依赖服务：
|
||
```bash
|
||
make up
|
||
```
|
||
|
||
3. 启动后端服务：
|
||
```bash
|
||
make api-dev
|
||
```
|
||
|
||
4. 启动 Flutter 应用：
|
||
```bash
|
||
make flutter-dev
|
||
```
|
||
|
||
### 2. 云端部署
|
||
|
||
1. 准备云端环境变量：
|
||
- 将 `.env.example` 中的变量映射到云平台 Secret
|
||
- 或创建 `infra/cloud/volcano/env/.env`（仅用于本地测试）
|
||
|
||
2. 修改配置指向云端：
|
||
```bash
|
||
# 示例：修改 .env 指向火山云托管地址
|
||
REDIS_URL=redis://volcano-redis:6379/0
|
||
MILVUS_URI=https://volcano-milvus:19530
|
||
DATABASE_URL=postgresql://user:pass@volcano-postgres/db
|
||
```
|
||
|
||
3. 部署应用：
|
||
- 通过 CI/CD 自动注入环境变量
|
||
- 或通过云平台控制台配置
|
||
|
||
## 配置优先级
|
||
|
||
从高到低：
|
||
1. 运行时环境变量（最高）
|
||
2. 环境文件（`.env`）
|
||
3. 配置文件（`configs/flutter/*.json`）
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何切换环境？
|
||
|
||
**本地开发**：使用 `configs/env/.env`
|
||
**云端部署**：使用云平台 Secret 注入
|
||
|
||
### Q: 如何确保 secret 不泄露？
|
||
|
||
- 所有 secret 变量使用 `CHANGE_ME` 占位符
|
||
- 本地配置文件（`configs/env/.env`、`infra/local/env/.env`）添加到 `.gitignore`
|
||
- 云端使用密钥管理服务注入
|
||
|
||
### Q: 如何测试云端配置？
|
||
|
||
1. 在本地创建 `infra/cloud/volcano/env/.env`（不提交）
|
||
2. 修改变量指向云端地址
|
||
3. 导出环境变量测试：
|
||
```bash
|
||
export $(cat infra/cloud/volcano/env/.env | xargs)
|
||
```
|
||
|
||
### Q: Compose 如何读取配置？
|
||
|
||
- 使用 `--env-file infra/local/env/.env` 注入本地 Supabase 栈变量
|
||
- Compose 文件为 `infra/local/docker-compose.yml`
|
||
- 应用代码通过 `os.getenv()` 读取本地应用变量
|