qzl/social-app

Fork 0

Files

T

qzl 6af0989fe7 chore: initial commit - Supabase stack with local Docker configuration

2026-01-28 15:21:06 +08:00

5.3 KiB

Raw Blame History

配置规则与使用原则

配置文件组织

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 仓库

创建方式：

cp configs/env/.env.example configs/env/.env
# 编辑 configs/env/.env，填入实际值

3. 本地 Supabase 栈配置

文件位置：infra/local/env/.env

作用：

本地 Supabase + 周边依赖的实际配置文件
从 infra/local/env/.env.example 复制后填入真实值
禁止提交到 Git 仓库

创建方式：

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 在构建时注入，运行时不可修改

示例：

# ✅ 正确：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() 或环境变量库

示例：

# ✅ 正确：通过环境变量读取
import os

database_url = os.getenv("DATABASE_URL")

# ❌ 错误：直接读取本地配置文件
from dotenv import load_dotenv
load_dotenv("configs/env/.env")  # 禁止

使用方式

1. 本地开发

复制环境变量模板：
```
make env
```
启动依赖服务：
```
make up
```
启动后端服务：
```
make api-dev
```
启动 Flutter 应用：
```
make flutter-dev
```

2. 云端部署

准备云端环境变量：
- 将 .env.example 中的变量映射到云平台 Secret

或创建 infra/cloud/volcano/env/.env（仅用于本地测试）

修改配置指向云端：

# 示例：修改 .env 指向火山云托管地址
REDIS_URL=redis://volcano-redis:6379/0
MILVUS_URI=https://volcano-milvus:19530
DATABASE_URL=postgresql://user:pass@volcano-postgres/db

部署应用：
- 通过 CI/CD 自动注入环境变量
- 或通过云平台控制台配置

配置优先级

从高到低：

运行时环境变量（最高）
环境文件（.env）
配置文件（configs/flutter/*.json）

常见问题

Q: 如何切换环境？

本地开发：使用 configs/env/.env 云端部署：使用云平台 Secret 注入

Q: 如何确保 secret 不泄露？

所有 secret 变量使用 CHANGE_ME 占位符
本地配置文件（configs/env/.env、infra/local/env/.env）添加到 .gitignore
云端使用密钥管理服务注入

Q: 如何测试云端配置？

在本地创建 infra/cloud/volcano/env/.env（不提交）
修改变量指向云端地址

导出环境变量测试：

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() 读取本地应用变量

5.3 KiB Raw Blame History Unescape Escape