SACTL 部署文档

4 种部署方式对比

按团队规模、运维能力、合规要求选。一句话: 个人/小团队走 Managed,中大团队走 K8s Helm,有特殊隔离要求走 Self-Hosted,海外项目方走 Edge。

Self-Hosted (Docker Compose)

适合: PoC、内部测试、单租户私有部署、开发环境。一台 Linux 服务器 (4 vCPU / 8GB RAM 起) 跑全栈。

一键起

git clone https://github.com/sactl/sactl-api.git
cd sactl-api

# 复制 env 模板,填上游 key + OAuth + SMTP
cp .env.example .env
vim .env

docker compose up -d

组件清单

• gateway-sidecar (Go) — 数据面热路径,认证 + 限流 + 计费 + 转发
• admin-api (Go) — 管理面,租户 / VK / 计费查询
• console (React) — 管理控制台 UI
• Portkey OSS — 上游路由 + Key Pool
• PostgreSQL 16 — 主存储
• Redis — 限流 GCRA + 计费缓存
• Vault — 密钥管理 (Provider key 加密)
• MinIO — Files API 二进制存储
• Nginx — TLS 终端 + 反代

首次初始化

make init  # 做 4 件事:
  # 1. vault operator init + unseal (5 keys, threshold 3)
  # 2. 运行 goose migrate
  # 3. 创建 default tenant + admin user
  # 4. 生成第一条 Virtual Key,打印一次 (sk-xa-prod-***)

升级 / 备份

• 升级: docker compose pull && docker compose up -d。Goose schema 迁移自动跑。
• 备份: 每月一次 pg_dump 全量 + Vault operator snapshot,上传到 S3 / MinIO。
• 滚动重启: docker compose restart gateway-sidecar (热路径无感知,因为有 Nginx 在前面)。

Managed Cloud

适合: 中小团队、不想运维基础设施、希望按月结算的客户。SACTL 官方托管全栈 (PostgreSQL、Redis、Vault、MinIO、监控告警),你只对接 API。

开通流程

1. 加 Telegram 客服,提供租户名 + 联系人 + 月度预算上限。
2. 客服 5 分钟内开通租户,发回 admin 后台地址 + 初始 sk-xa-* Virtual Key。
3. 登录后台,创建额外 VK、配置月预算上限、IP 白名单、allowed_models。
4. 客户端把 base_url 指向 https://api.sactl.ai 即可。

跟 Self-Hosted 比的差异

• 不需要自己跑 Vault / Postgres / Redis / MinIO,SACTL 包了。
• 计费按 token 实扣(Claude × 0.30、GPT 低至官方 1/30),没有额外月度服务费。
• SLA: Managed 标准 99.5%,大客户可议年度框架价升 99.9%。
• 合规: 走 SACTL 的合规栈 (日志白名单、PII 不落盘、HMAC VK)。如果你有强数据本地化要求,选 Self-Hosted 或 K8s。

具体方案聊 Telegram,价格按用量定。

Kubernetes (Helm)

适合: 中大型客户、需要多 AZ 高可用、希望复用现有 RDS / ElastiCache / Vault 中间件、需要 HPA 自动扩缩容。

values.prod.yaml 片段

gatewaySidecar:
  replicas: 6
  resources:
    requests: {cpu: "500m", memory: "512Mi"}
    limits: {cpu: "2", memory: "2Gi"}
  hpa:
    enabled: true
    minReplicas: 3
    maxReplicas: 30
    targetCPUUtilizationPercentage: 60

postgres:
  external: true
  dsn: "postgres://sactl:***@rds.internal:5432/sactl?sslmode=require"

redis:
  external: true
  addr: "elasticache.internal:6379"

minio:
  external: true
  endpoint: "s3.amazonaws.com"  # 或直接用 AWS S3

vault:
  external: true
  addr: "https://vault.internal:8200"
  approle: {role_id: "...", secret_id: "..."}

安装 / 升级

# 添加 repo
helm repo add sactl https://charts.sactl.ai
helm repo update

# 首次安装
helm install sactl sactl/sactl-gateway \
  -f values.prod.yaml \
  -n sactl --create-namespace

# 升级到指定版本
helm upgrade sactl sactl/sactl-gateway \
  -f values.prod.yaml --version=N

# 回滚
helm rollback sactl PREVIOUS

外置托管组件

• RDS Postgres 16 推荐 db.r6g.large 起,启用 PITR。
• ElastiCache Redis: cluster mode disabled,m6g.large 起即可。
• Vault: 自建或 HashiCorp Cloud。AppRole 认证,role_id / secret_id 通过 ExternalSecret 注入。
• S3 / MinIO: 任一 S3-compatible 都行。文件按 lifecycle 30 天自动清理。

Cloudflare Workers 边缘代理

适合: 海外项目方、用户分布在 200+ 国家、对国际加速敏感。把认证、限流、上游路由推到 Cloudflare 边缘,减少跨地域延迟。

目录

仓库子目录 deploy/edge-proxy/cloudflare-workers/,包含 Worker 代码、wrangler.toml 模板、KV namespace 定义、CF Rate Limiting Rules 配置。

能力

• Rate limit: CF Rate Limiting Rules + Worker KV 做轻量 GCRA 限流
• 认证: 校验 sk-xa-* prefix + 透传到自建后端做 HMAC 验证
• 路由: 边缘节点选最近的 SACTL 自建 origin (东京 / 法兰克福 / 弗吉尼亚)
• 缓存: 不缓存 prompt / response 体 (透传服务规则一致),只缓存 /v1/models 这种元数据

部署

cd deploy/edge-proxy/cloudflare-workers
wrangler login

# 改 wrangler.toml: account_id / kv_namespaces.id / routes
vim wrangler.toml

# 灌 secrets
wrangler secret put SACTL_UPSTREAM_URL
wrangler secret put SACTL_VAULT_TOKEN

# 部署
wrangler deploy

# 灰度: 先切 5%,观察 24h
# CF Dashboard → Workers Routes → 设置流量百分比