forked from wangziqi/gongxue-base
155 lines
4.6 KiB
Markdown
155 lines
4.6 KiB
Markdown
# 本地 Supabase 开发环境
|
||
|
||
## 前置依赖
|
||
|
||
Supabase 本地开发需要：
|
||
|
||
- Docker Desktop
|
||
- Supabase CLI
|
||
- Node.js 20+
|
||
|
||
当前机器如果出现下面错误，说明 Docker Desktop 未启动或 Docker daemon 不可访问：
|
||
|
||
```text
|
||
failed to inspect container health
|
||
open //./pipe/docker_engine: The system cannot find the file specified
|
||
```
|
||
|
||
先启动 Docker Desktop，再执行 Supabase 命令。
|
||
|
||
当前仓库已经加入 `supabase/config.toml` 和第一版 migration。安装依赖后执行：
|
||
|
||
```bash
|
||
npm run supabase:start
|
||
npm run supabase:status
|
||
```
|
||
|
||
本地默认端口：
|
||
|
||
```text
|
||
API: http://127.0.0.1:54321
|
||
DB: postgresql://postgres:postgres@127.0.0.1:54322/postgres
|
||
Studio: http://127.0.0.1:54323
|
||
Inbucket: http://127.0.0.1:54324
|
||
```
|
||
|
||
重置数据库：
|
||
|
||
```bash
|
||
npm run supabase:reset
|
||
npm run db:smoke-seed -- --confirm=SMOKE_SEED_LOCAL_OR_CI_ONLY
|
||
```
|
||
|
||
`supabase:reset` 执行本地 `supabase/seed.sql`，会在 `app_private.environment_safety` 写入唯一的 `local/true` 标记。`smoke-seed` 还要求精确确认短语，两者缺一即在事务和任何持久化写入前拒绝。`npm run test:api`、`npm run test:rls` 和 `test:worker:*` 会通过受控 npm script 传入确认值，但仍必须通过数据库标记。
|
||
|
||
CI 或生产快照的隔离克隆库需由初始化流程显式写入 `environment='ci'` 或 `test`、`allow_destructive_tests=true`，并只授予测试数据库角色读取该标记的权限。生产和预发不得设置放行标记，也不得执行 `supabase/seed.sql`。
|
||
|
||
## API 服务
|
||
|
||
```bash
|
||
npm run dev:api
|
||
```
|
||
|
||
健康检查：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8787/health
|
||
```
|
||
|
||
租户解析：
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:8787/api/tenant/resolve?host=localhost"
|
||
curl "http://127.0.0.1:8787/api/tenant/resolve?tenantCode=master"
|
||
```
|
||
|
||
公开题库数据接口示例：
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:8787/api/catalog/regions?tenantId=00000000-0000-0000-0000-000000000001"
|
||
curl "http://127.0.0.1:8787/api/catalog/questions?tenantId=00000000-0000-0000-0000-000000000001&limit=20"
|
||
```
|
||
|
||
本地短信登录 smoke 可用 mock provider。开发环境接口会返回 `debugCode`：
|
||
|
||
```bash
|
||
curl -X POST "http://127.0.0.1:8787/api/auth/sms/send" \
|
||
-H "content-type: application/json" \
|
||
-H "x-tenant-id: 00000000-0000-0000-0000-000000000001" \
|
||
-d "{\"phone\":\"13900000001\",\"purpose\":\"login\"}"
|
||
```
|
||
|
||
平台运营接口迁移期使用 `x-platform-admin-key`。本地默认值来自 `PLATFORM_ADMIN_API_KEY`，未设置时为 `local-platform-admin-key`：
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:8787/api/platform-admin/overview" \
|
||
-H "x-platform-admin-key: local-platform-admin-key"
|
||
|
||
curl "http://127.0.0.1:8787/api/platform-admin/tenants?limit=20" \
|
||
-H "x-platform-admin-key: local-platform-admin-key"
|
||
```
|
||
|
||
## Docker 运行 API
|
||
|
||
本地 Supabase 继续由 Supabase CLI 启动，API 可以单独进入 Docker 容器：
|
||
|
||
```bash
|
||
npm run supabase:start
|
||
npm run docker:api:build
|
||
npm run docker:api:up
|
||
```
|
||
|
||
Compose 文件是 `docker-compose.api.yml`。API 容器默认使用：
|
||
|
||
```text
|
||
DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:54322/postgres
|
||
PORT=8787
|
||
```
|
||
|
||
如果本机已有非容器 API 占用 `8787`，先关闭旧进程或临时修改 `docker-compose.api.yml` 的端口映射。当前机器 Docker Desktop 可用，Supabase 容器已可运行；若构建 API 镜像时报 Docker Hub 或 ECR 拉取超时，需要先处理 Docker 镜像源或网络代理。
|
||
|
||
## PocketBase JSON 导入
|
||
|
||
把 PocketBase 导出的集合 JSON 放到仓库根目录的 `pb_export` 文件夹后执行：
|
||
|
||
```bash
|
||
npm run pb:import:dry-run
|
||
npm run pb:import:json
|
||
npm run pb:import:validate
|
||
```
|
||
|
||
`pb:import:dry-run` 不写数据库，会先检查 JSON 格式、核心集合、旧 ID、敏感字段、关系断裂和未映射集合。存在 blocker 时先处理问题，不要直接正式导入。
|
||
|
||
真实生产数据迁移请按完整验收流程执行：
|
||
|
||
```text
|
||
docs/refactor/pocketbase-real-data-migration-runbook.md
|
||
```
|
||
|
||
正式切换前建议先跑严格 dry-run：
|
||
|
||
```bash
|
||
npm run pb:import:dry-run -- --json --fail-on-warnings
|
||
```
|
||
|
||
导入后校验如需把 warning 也视为阻断：
|
||
|
||
```powershell
|
||
$env:FAIL_ON_WARNINGS="true"
|
||
npm run pb:import:validate
|
||
Remove-Item Env:\FAIL_ON_WARNINGS
|
||
```
|
||
|
||
导入真实密钥时必须明确打开开关，且只允许进入 `app_private.tenant_secrets`：
|
||
|
||
```bash
|
||
set IMPORT_SECRET_VALUES=true
|
||
npm run pb:import:json
|
||
```
|
||
|
||
上线前 `pb:import:validate` 不能有 `FAIL`。`WARN` 通常代表旧数据缺失关联，需要业务确认后记录处理结论。
|
||
|
||
## 说明
|
||
|
||
Supabase Custom Domain 不用于合作商多域名绑定。合作商域名在你们自己的 Web/API 网关层解析，然后从 `tenant_domains` 表得到 `tenant_id`。
|