chore: initial commit - Supabase stack with local Docker configuration
This commit is contained in:
qzl
@@ -0,0 +1,203 @@
|
||||
# 配置规则与使用原则
|
||||
|
||||
## 配置文件组织
|
||||
|
||||
### 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()` 读取本地应用变量
|
||||
@@ -0,0 +1,21 @@
|
||||
# 目录结构规则
|
||||
|
||||
## 顶层目录（必须遵守）
|
||||
|
||||
仓库根目录只能包含以下目录：
|
||||
|
||||
- `apps/` —— 可运行应用（Flutter / FastAPI / Worker）
|
||||
- `infra/` —— 基础设施（本地 docker / 云部署 / 迁移）
|
||||
- `configs/` —— 配置规范与公共配置模板（不含密钥）
|
||||
- `tools/` —— 脚本与生成器
|
||||
- `docs/` —— 文档与规则
|
||||
- `.github/`（可选，用于 CI/CD）
|
||||
- `README.md`
|
||||
- `Makefile`（可选）
|
||||
|
||||
## 禁止事项
|
||||
|
||||
- 禁止在根目录直接出现：`backend/`、`ui/`、`docker/`、`scripts/` 等非规范目录
|
||||
- 所有业务代码必须放在 `apps/` 目录下
|
||||
- 所有配置文件必须放在 `configs/` 目录下
|
||||
- 所有基础设施相关代码必须放在 `infra/` 目录下
|
||||
Reference in New Issue
Block a user