Keel 自建部署

本文档面向想自建 Keel 后端服务（不用 Keel 托管商业版）的开发者 / 企业。所有 Keel 服务端代码 Apache 2.0 开源，可以自己跑。

大多数开发者不需要看这个——直接用 Keel Pro / Team / Enterprise 托管版，省运维。本文档只对：

  • 数据出境合规要求严格的客户
  • 私有云 / 内网部署需求
  • 想完全控制 / 二开的爱好者

…这几类人有用。

自建 vs 托管

维度托管版（Pro / Team / Enterprise）自建
运维Keel 团队你自己
SLA有（详见 pricing.md）无（社区支持）
升级自动手动
计费¥/月订阅自付云资源（阿里云 / 腾讯云 / 自建机房）
功能完整完整（不阉割，跟商业版一样的代码）
合规Keel 走 ICP 备案 + 合规通道你自己负责

5 个服务可独立部署

Keel 后端是模块化的，每个服务独立可以跑：

服务必须 / 可选说明
Build可选（不需要云端 build 就不装）Docker pipeline；跑 metro + Hermes
Update Service可选（用 App Store 直接更新就不装）manifest endpoint + bundle CDN
Push Service可选（路线图）包 极光 / 个推 server API
(removed)可选（路线图，仅 web target 用得上）静态资源 + CDN
Identity / Account API可选Keel 用户账号（自建可以走自家 SSO）

当前自建场景 = Build + Update Service。其他可以等需要再加。

最小自建

前置依赖

  • 一台 Linux 服务器（4 vCPU / 8 GB 内存起，Build 需要更大）
  • Docker + Docker Compose
  • PostgreSQL 14+ 或 SQLite（Update manifest）
  • 任意 S3 兼容对象存储（OSS / R2 / S3 / MinIO）+ CDN（阿里云 / Cloudflare / 自建）
  • 域名 + HTTPS 证书（Let’s Encrypt 免费）

启动 Build

# 拉 Keel 后端代码
git clone https://github.com/appunvs/appunvs.git
cd appunvs/keel/cloud/build-image

# 构建 Docker 镜像（含 metro + Hermes + iOS / Android toolchain）
docker build -t keel/cloud/build-image:self-host .

# 启动构建器（需要 Docker-in-Docker 或 mounted /var/run/docker.sock）
docker run -d \
  --name keel-cloud-build \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/keel/builds:/work \
  -p 8080:8080 \
  -e KEEL_BUILD_DIR=/work \
  -e KEEL_API_KEY=$YOUR_PRIVATE_API_KEY \
  keel/cloud/build-image:self-host

⚠️ 目前这个 image 还在 internal 状态——keel/cloud/build-image/ 当前是给 appunvs 内部 AI bundle 构建用的，把它包装成对外 service 是路线图任务。本文档先占位。

启动 Update Service

# Update service 是个 Go binary
cd keel/cloud/cmd/update-server
go build -o keel-update-server .

# 当前 backend 只支持 mem + sqlite；Postgres 在路线图上。
# 生产端用 SQLite（单实例够 100k 设备的 polling）。
./keel-update-server \
  --db "sqlite:/var/lib/keel/update.db" \
  --listen ":8081"

# S3/OSS bundle 存储 + CDN 通过 env 配（不是命令行 flag）：
#   KEEL_UPDATE_BLOB_STORE=s3
#   KEEL_UPDATE_S3_BUCKET=keel-bundles
#   KEEL_UPDATE_S3_REGION=cn-hangzhou
#   KEEL_UPDATE_S3_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
#   KEEL_UPDATE_S3_ACCESS_KEY=<RAM ak>
#   KEEL_UPDATE_S3_SECRET_KEY=<RAM sk>
#   KEEL_UPDATE_PUBLIC_URL_BASE=https://cdn.your-domain.com
# 详见 deployment-sop.md 完整 systemd + nginx 模板。

CLI 配置指向自建后端

开发者本地 keel/config.yaml（在项目里）：

endpoint:
  cloud_build: https://your-keel-cloud-build.com
  ota: https://your-keel-update-server.com
  api_key: $KEEL_API_KEY

keel build ios / keel publish 自动用配置里的 endpoint。

阿里云推荐栈

国内自建首选阿里云：

服务阿里云对位备注
Build 容器ECI（弹性容器实例）/ ACK（容器服务）ECI 按秒计费，按需起，关掉就停；ACK 适合大流量
Update / Push 服务ECS + 本机 SQLite一台 2c4g 起步（当前 backend = SQLite，Postgres 选项在路线图上）
Bundle 存储OSS（标准存储）0.12 ¥/GB-月
CDN阿里云 CDN0.24 ¥/GB egress（国内）
域名 + ICP 备案阿里云域名 + ICPICP 备案 ~10 工作日

最小可用配置（< 50 Update MAU 测试规模）：

  • 1 台 ECS 4c8g（Update + Build orchestrator + 本机 SQLite）= ~¥260/月
  • OSS + CDN（按用量，~¥30/月起）
  • 后续加 Postgres 选项后：另起 RDS PG mini ~¥500/月（可选，SQLite 够用就不必）
  • 域名 + 证书：~¥80/年

总：~¥900/月（按 RDS）or ~¥350/月（SQLite 小规模）

跟 Keel Pro ¥48/月 vs 自建 ¥350+/月 —— 自建只在你有合规要求 / 想完全控制时才划算。一般用户直接 Pro 更省事。

Build 基础设施对位（vs Expo EAS）

Keel GA 的 Build 选型跟 Expo EAS 做了一次完整对照。决策原则：国内合规 + 计费形状匹配 build 负载（每个 build 30s–3min 短任务，闲时归零）。

维度Expo / EASKeel GA选型理由
iOS buildAWS mac1/mac2 EC2 + Xcode + fastlanemacOS runner（自管 mac mini 池 / MacStadium 租用 / 当前可选跳过）Docker 跑不了 Xcode；macOS 必须有真机或 mac 实例。当前可文档标注「iOS 需 self-host mac runner」，先打通 android/web
Android buildAWS EC2 Linux + Gradle + Android SDK阿里云 ECI（Linux 容器 + Gradle + Android SDK + 用户上传 keystore）国内合规 + ECI 按秒计费，build 完关掉就停
Web / JS bundleAWS EC2 Linux + Metro阿里云 ECI（Metro 容器）同上；JS bundle 无平台 toolchain 依赖，最轻
Hermes 字节码EAS 自动跟 Metro 同容器内 hermesc -emit-binary（build-bundle.sh 已支持）一步出 .bundle + .hbc
Worker 池调度自管 pool（早期 Concourse → self-built）当前：os/exec docker 直接起 ECI ；后续看流量再做 pool启动期不抢调度复杂度；ECI cold start ~5s 可忍
Artifact 存储S3 + CloudFrontOSS + 阿里云 CDN国内 egress 0.24 ¥/GB；OSS 0.12 ¥/GB-月
Provisioning / signingEAS 后端集中管理用户自管（CLI 上传 keystore / cert，server 不持久化）当前不碰 cert escrow，安全边界清晰；后续看需求再做 EAS 同款
计费按 build 次数（mac vs linux 分级）按 build 次数（pricing.md Pro 档每月配额，超出按量）mac build 单价高（mac1 实例 ~¥3/min），价格层级后续再分
Cold startEC2 boot ~30sECI 启动 ~5s（已 pull image）/ ~30s（首次 pull）短 build 也能划算

为什么不选 FC（函数计算）？

阿里云 FC 也能跑 docker image，但：

  • FC 计费维度多（请求次数 + 执行时长 + 资源大小），跟 pricing.md 的「builds/月」配额映射麻烦
  • FC 镜像 cold start 比 ECI 慢，OCI image 灵活度也低
  • ECI 价格、配额、生命周期 API 都更直白，跟 build job state machine 1:1 对应

为什么当前不上 ACK / Kubernetes？

ACK（容器服务 Kubernetes）适合常驻 worker 池 + 高 QPS 场景。当前测试规模 < 50 builds/天，ECI on-demand 起停就够；Kubernetes 调度复杂度 + 维护成本现在不值。流量起来（~1000 builds/天）后再评估迁 ACK。

海外自建栈

如果你是海外用户（Keel 暂不开放海外，但代码 Apache 2.0 你可以自己跑）：

服务推荐
BuildAWS ECS / GCP Cloud Run / Fly.io
数据库Neon / Supabase Postgres / RDS
对象存储S3 / R2 / Cloudflare
CDNCloudflare / Fastly
域名 + HTTPSLet’s Encrypt 免费

升级策略

自建版 Keel 后端的升级：

  1. 关注 GitHub Releases（已规范化 release）
  2. 每个 minor 版本（0.x）都向后兼容；major 版本（X.0）会有 migration guide
  3. 升级前看 docs/roadmap.md 的 breaking changes 列表
  4. 滚动升级：先升一台 Update / Build replica，验证后再升其他

CI 加自动升级 PR 的好习惯（dependabot 等价）—— 后续会出 keel-action GitHub Action 帮你做。

数据迁移：托管 → 自建 / 自建 → 托管

托管版导出（路线图）：

keel export --workspace=your-ws --to=./backup.tar.gz

导出包含：所有 Update bundle + manifests + push subscriptions + project metadata。

自建版导入：

keel-update-server import --from=./backup.tar.gz

反向也支持（自建 → 托管）。这是 GitLab / Sentry 自建可迁移的同套理念。

安全

自建场景下你自己负责：

  • HTTPS 证书 + 续签
  • 数据库备份策略（建议 PG WAL + S3 异地备份）
  • API key 管理
  • 防火墙 / SG 配置
  • 日志 + audit trail
  • DDoS 防护（云厂商基础版够小流量；高流量需要 WAF）

参考企业部署清单：企业部署 checklist。

跟商业版的功能 parity 承诺

承诺：Keel 自建版功能上跟商业版完全一样。商业版不阉割开源版。

商业版卖的是：

  • 托管运维（不用你自己搞 DB / CDN / 监控）
  • SLA（24h / 4h 工单响应）
  • 优先 build 队列（busy 时段不用排队）
  • 团队 / 企业级账号管理
  • 对公开票

代码功能 = 完全一致。

企业部署 checklist

（后续完整撰写；现在草稿）

  • HA 部署（Update 服务 ≥ 2 replicas + LB）
  • Database HA（PG 主从 / 多副本）
  • 对象存储跨区域复制
  • CDN 多 edge 配置
  • 监控告警（Prometheus + Grafana 等）
  • 日志聚合（ELK / Loki / SLS 等）
  • Audit log 长期归档
  • 数据库备份（≥ 每日 + 异地）
  • 灾备演练
  • 安全 hardening（最小权限 / 网络分段 / WAF）
  • 合规：ICP 备案 / 数据出境申报（如适用）
  • 私有 npm 镜像（防 npm.org 不可达）

常见问题

Q: 自建 Keel 还能用 Keel Go tester app 吗？

可以，但需要重定向到你的自建后端。Keel Go 启动时输入 endpoint URL；指向你的 Update service / Build endpoint 即可。或自己 fork Keel Go + rebuild 一个 brand 化的 tester。

Q: 自建版能接 Mortar 吗？

能——但 Mortar 是另一个独立产品。自建 Keel 跟用 Mortar Cloud（托管）/ Mortar 自建版（也开源）都解耦，正交不冲突。详见 Mortar deployment。

Q: License 限制？

Apache 2.0 —— 想 fork / 商业用 / 改名都可以。唯一限制：不能用 “Keel” 名字 / logo 宣传你的衍生品（按 license § 6 商标条款）。

详见 LICENSE + governance.md。

Q: 自建版有没有付费支持？

后续会出 Enterprise Support 合同（24h SLA + 私有部署 + 安全更新）。详见 pricing.md Enterprise 档。

报 issue / 求助

在 GitHub 上编辑 →