本地 Supabase 开发环境

前置依赖

Supabase 本地开发需要：

Docker Desktop
Supabase CLI
Node.js 20+

当前机器如果出现下面错误，说明 Docker Desktop 未启动或 Docker daemon 不可访问：

failed to inspect container health
open //./pipe/docker_engine: The system cannot find the file specified

先启动 Docker Desktop，再执行 Supabase 命令。

当前仓库已经加入 supabase/config.toml 和第一版 migration。安装依赖后执行：

npm run supabase:start
npm run supabase:status

本地默认端口：

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

重置数据库：

npm run supabase:reset
npm run db:smoke-seed

API 服务

npm run dev:api

健康检查：

curl http://127.0.0.1:8787/health

租户解析：

curl "http://127.0.0.1:8787/api/tenant/resolve?host=localhost"
curl "http://127.0.0.1:8787/api/tenant/resolve?tenantCode=master"

公开题库数据接口示例：

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：

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：

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 容器：

npm run supabase:start
npm run docker:api:build
npm run docker:api:up

Compose 文件是 docker-compose.api.yml。API 容器默认使用：

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 文件夹后执行：

npm run pb:import:json
npm run pb:import:validate

导入真实密钥时必须明确打开开关，且只允许进入 app_private.tenant_secrets：

set IMPORT_SECRET_VALUES=true
npm run pb:import:json

上线前 pb:import:validate 不能有 FAIL。WARN 通常代表旧数据缺失关联，需要业务确认后记录处理结论。

说明

Supabase Custom Domain 不用于合作商多域名绑定。合作商域名在你们自己的 Web/API 网关层解析，然后从 tenant_domains 表得到 tenant_id。

3.3 KiB Raw Blame History Unescape Escape

本地 Supabase 开发环境

前置依赖

API 服务

Docker 运行 API

PocketBase JSON 导入

说明

3.3 KiB

Raw Blame History