Docker 部署

Docker 路径适合：内网 / VPC、生产在自有机器或 K8s 上托管、以及希望 数据落在 Postgres/MySQL 且与现有 DBA 流程一致的场景。默认推荐仍是 Cloudflare Workers（个人与小流量通常可走免费额度）。

本地一键体验

git clone https://github.com/OctaFuse/octafuse-gateway.git
cd octafuse-gateway
docker compose -f docker/compose/quickstart.yml up --build

该 Compose 配置会启动 Postgres + 迁移任务 + 代理服务 + 管理后台：

代理服务：http://localhost:8787
管理后台：http://localhost:8789，默认登录凭证为 admin / changeme
默认管理 Bearer 密钥：sk-dev-admin-key

如果本机端口冲突，可通过 POSTGRES_HOST_PORT、GATEWAY_PROXY_HOST_PORT、GATEWAY_ADMIN_HOST_PORT 调整宿主机端口。Cloudflare 默认路径见快速开始。

生产自建怎么跑

生产通常有两种做法：本地构建镜像，或使用发布到 GHCR / 私有镜像仓库（registry） 的预构建镜像。两种方式都建议遵循先迁移，再启动代理服务 / 管理后台；或者只在一个服务上启用 AUTO_MIGRATE=1。

方式 A：本地构建镜像 + 内置数据库

Postgres：

docker compose -f docker/compose/node-pg.yml up -d postgres
docker compose -f docker/compose/node-pg.yml --profile migrate run --rm migrate
docker compose -f docker/compose/node-pg.yml up -d gateway-proxy gateway-admin

MySQL 8：

docker compose -f docker/compose/node-mysql.yml up -d mysql
docker compose -f docker/compose/node-mysql.yml --profile migrate run --rm migrate
docker compose -f docker/compose/node-mysql.yml up -d gateway-proxy gateway-admin

MySQL 场景必须设置 DATABASE_DRIVER=mysql，并使用 mysql://... 形式的 DATABASE_URL。

方式 B：预构建镜像 + 外置 Postgres

docker/examples/ 提供生产常用的拆分模板：仅运行代理服务、仅运行管理后台，或在同一台机器上同时启动两者。环境文件不要提交到 Git，建议放在 docker/deploy/。

cp docker/examples/env.compose.external.example docker/deploy/.env.local
# 编辑 docker/deploy/.env.local：镜像 tag、DATABASE_URL、ADMIN_PASSWORD 等
docker compose --env-file docker/deploy/.env.local -f docker/examples/gateway.compose.yml --profile migrate run --rm migrate
docker compose --env-file docker/deploy/.env.local -f docker/examples/gateway.compose.yml up -d

镜像名随你的仓库或镜像仓库变化，格式通常是：

ghcr.io/<owner>/<repo>-proxy:<tag>
ghcr.io/<owner>/<repo>-admin:<tag>
ghcr.io/<owner>/<repo>-migrate:<tag>

方式 C：单独构建镜像

仓库根目录提供三个 Dockerfile：

docker build -f Dockerfile.proxy -t octafuse-proxy:local .
docker build -f Dockerfile.admin -t octafuse-admin:local .
docker build -f Dockerfile.migrate -t octafuse-migrate:local .

Dockerfile.migrate 是一次性迁移作业（Job）；Dockerfile.proxy 与 Dockerfile.admin 是常驻应用进程。

如何更新版本

升级前先阅读该版本的 GitHub 发布说明（Release） / 更改日志（Changelog）中的升级说明（是否有破坏性变更、是否必须先迁移）。推荐顺序始终是：先迁移，再滚动重启代理服务 / 管理后台（或只在一侧启用 AUTO_MIGRATE=1）。

预构建镜像（GHCR / 私有镜像仓库）

在 docker/deploy/.env.local（或你的环境文件）中，把 GATEWAY_PROXY_IMAGE / GATEWAY_ADMIN_IMAGE / GATEWAY_MIGRATE_IMAGE 的**标签（tag）**改成目标版本（例如 v2.1.2；生产环境建议固定语义化版本，避免长期使用 latest）。
拉取并迁移，再重建容器：

docker compose --env-file docker/deploy/.env.local -f docker/examples/gateway.compose.yml pull
docker compose --env-file docker/deploy/.env.local -f docker/examples/gateway.compose.yml --profile migrate run --rm migrate
docker compose --env-file docker/deploy/.env.local -f docker/examples/gateway.compose.yml up -d

若已启用 AUTO_MIGRATE=1，可在 pull 后直接执行 up -d（入口会在启动前执行幂等迁移）；仍建议先查看发布说明，确认本版迁移是否需要维护窗口。

本地构建镜像（方式 A / C）

git pull --ff-only
# 有新 SQL 时先迁移
docker compose -f docker/compose/node-pg.yml --profile migrate run --rm migrate
# 再重建并启动应用（MySQL 则改用 node-mysql.yml）
docker compose -f docker/compose/node-pg.yml up -d --build gateway-proxy gateway-admin

本地一键体验（quickstart.yml）同理：git pull 后 docker compose -f docker/compose/quickstart.yml up --build -d。

升级后验收

curl -fsS http://127.0.0.1:8787/health
curl -fsS http://127.0.0.1:8789/api/admin/config \
  -H 'Authorization: Bearer <MASTER_KEY>'

更详细的镜像名、GHCR 摘要（digest）与 Zeabur 注意事项见 GitHub · Docker / 自托管。

关键环境变量

DATABASE_URL：代理服务、管理后台和迁移任务必须指向同一个数据库。
DATABASE_DRIVER：Postgres 可省略；MySQL 必须为 mysql。
ADMIN_USERNAME / ADMIN_PASSWORD：管理后台登录账号，仅管理后台容器需要。
AUTO_MIGRATE：可选。设为 1 时，应用容器会在启动前自动执行幂等迁移；生产环境也可以改用独立迁移作业。
GATEWAY_PROXY_PORT / GATEWAY_ADMIN_PORT：仅影响宿主机端口映射；容器内仍监听 8787 / 8789。

Postgres 建议让连接或实例保持 UTC；如果用 DATABASE_URL 控制，可附加 options=-c timezone=UTC。MySQL 也建议实例或会话统一为 UTC，避免时间窗口查询排障困难。

发布后验证

curl -fsS http://127.0.0.1:8787/health
curl -fsS http://127.0.0.1:8789/api/admin/config \
  -H 'Authorization: Bearer sk-dev-admin-key'

与 Cloudflare 方案如何选

需要 完全掌控数据落点、内网互通、已有容器平台 → 优先 Docker 自建。
需要 全球边缘、少运维机器 → 见 Cloudflare Workers 部署。