Sign inSign up

longjianghu/zentrola

By longjianghu

•Updated 4 days ago

Image
0

804

longjianghu/zentrola repository overview

⁠Zentrola

Zentrola 是面向研发团队的企业 AI Coding 能力治理平台，位于 Codex、Claude Code 等 AI Coding Client 与企业模型订阅之间。

它可以集中管理 Provider、Credential、逻辑模型、成员、Group、Virtual Key、调用用量和操作记录，并提供 OpenAI 与 Anthropic 兼容接口、协议转换及 Provider 故障切换。

⁠镜像说明

同一个镜像包含两个程序：

启动命令用途默认端口
backendBackend、Admin API 和模型 Gateway9527
webAdmin Web 管理界面9528

推荐使用项目提供的 Docker Compose 配置，同时启动 Zentrola、PostgreSQL 17 和 Redis。

⁠快速部署

⁠1. 下载 Compose 配置
curl -fsSLO https://raw.githubusercontent.com/zentrola/zentrola/main/compose.yaml

也可以直接从 GitHub 下载：

https://github.com/zentrola/zentrola/blob/main/compose.yaml⁠

需要 Docker Compose 2.23.1 或更高版本。

⁠2. 修改密码和密钥

打开 compose.yaml，修改文件顶部 x-required-settings 下的四项配置：

x-required-settings:
  postgres-password: &postgres-password "REPLACE_WITH_STRONG_POSTGRES_PASSWORD"
  redis-password: &redis-password "REPLACE_WITH_STRONG_REDIS_PASSWORD"
  admin-jwt-secret: &admin-jwt-secret "REPLACE_WITH_BASE64_32_BYTE_SECRET"
  master-key-file: &master-key-file |
    MASTER_KEY=REPLACE_WITH_BASE64_32_BYTE_KEY

要求：

  • postgres-password：PostgreSQL 高强度密码
  • redis-password：Redis 高强度密码
  • admin-jwt-secret：至少 32 个随机字节的 Base64 字符串
  • MASTER_KEY：另一组独立的 32 个随机字节的 Base64 字符串

可以使用以下命令生成随机密钥：

openssl rand -base64 32

请分别生成 ADMIN_JWT_SECRET 和 MASTER_KEY，不要重复使用同一个值。

MASTER_KEY 用于加密 Provider Credential。必须与 PostgreSQL 数据一起备份；丢失后，数据库中已有的 Provider Credential 将无法解密。

⁠3. 启动完整服务栈
docker compose up -d

服务启动后：

打开 Admin Web 后创建首位管理员。Zentrola 不提供默认用户名或密码。

⁠4. 查看运行状态
docker compose ps
docker compose logs -f backend

Backend 健康检查：

curl -fsS http://127.0.0.1:9527/health/live
curl -i http://127.0.0.1:9527/health/ready
  • /health/live：Backend 可以响应 HTTP 请求
  • /health/ready：检查 PostgreSQL、Master Key 和管理员初始化状态
⁠5. 停止和重新启动

停止服务但保留数据：

docker compose stop

重新启动：

docker compose start

更新配置或镜像后重新创建容器：

docker compose up -d

不要把 docker compose down -v 作为日常停止命令。该命令会永久删除 PostgreSQL、Redis 和 Zentrola 的命名数据卷。

⁠拉取镜像

docker pull longjianghu/zentrola:1.0.0

建议生产部署固定使用明确的版本号，而不是依赖浮动标签。

⁠单独运行 Backend

生产环境推荐直接使用项目提供的 compose.yaml。如果需要连接已有的 PostgreSQL 和 Redis，可以单独启动 Backend：

docker run -d \
  --name zentrola-backend \
  --restart unless-stopped \
  -p 9527:9527 \
  -e APP_ENV=prod \
  -e HTTP_ADDR=:9527 \
  -e POSTGRES_HOST=postgres.example.com \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_DB=zentrola \
  -e POSTGRES_USER=zentrola \
  -e POSTGRES_PASSWORD=REPLACE_WITH_STRONG_PASSWORD \
  -e POSTGRES_SSLMODE=require \
  -e REDIS_HOST=redis.example.com \
  -e REDIS_PORT=6379 \
  -e REDIS_DB=2 \
  -e REDIS_PASSWORD=REPLACE_WITH_REDIS_PASSWORD \
  -e ADMIN_JWT_SECRET=REPLACE_WITH_BASE64_32_BYTE_SECRET \
  -e MIGRATIONS_AUTO_APPLY=true \
  -e CORS_ENABLED=true \
  -e CORS_ALLOWED_ORIGINS=https://zentrola.example.com \
  -v /absolute/path/to/zentrola.env:/app/.env:ro \
  -v zentrola_data:/app/data \
  longjianghu/zentrola:1.0.0 \
  backend

挂载到 /app/.env 的文件至少需要包含：

MASTER_KEY=REPLACE_WITH_BASE64_32_BYTE_KEY

MASTER_KEY 只能从 Backend 选定的通用配置文件读取，不能仅通过容器环境变量传入。

生产数据库应启用 TLS，并设置适当的 POSTGRES_SSLMODE。

⁠单独运行 Admin Web

docker run -d \
  --name zentrola-web \
  --restart unless-stopped \
  -p 9528:9528 \
  -e WEB_ADDR=:9528 \
  -e WEB_API_BASE_URL=https://api.example.com \
  -e WEB_GATEWAY_BASE_URL=https://api.example.com \
  longjianghu/zentrola:1.0.0 \
  web \
  --api https://api.example.com \
  --gateway https://api.example.com

WEB_API_BASE_URL 和 WEB_GATEWAY_BASE_URL 必须是用户浏览器和 AI Client 能够访问的地址，不能填写仅容器内部可见的主机名。

同时需要在 Backend 中设置：

CORS_ENABLED=true
CORS_ALLOWED_ORIGINS=https://zentrola.example.com

⁠完成第一次模型调用

登录 Admin Web 后：

  1. 初始化或创建 Provider。
  2. 添加 Provider Credential。
  3. 测试连接并同步或配置 Provider Model。
  4. 启用逻辑模型及其 Provider Model 映射。
  5. 创建成员和 Group。
  6. 将成员加入 Group，并向 Group 授权逻辑模型。
  7. 为成员签发 Virtual Key。

验证 OpenAI 兼容模型列表：

curl http://127.0.0.1:9527/v1/models \
  -H "Authorization: Bearer <virtual-key>"

发送 OpenAI 兼容对话请求：

curl http://127.0.0.1:9527/v1/chat/completions \
  -H "Authorization: Bearer <virtual-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"<logical-model-code>","messages":[{"role":"user","content":"你好"}]}'

Anthropic 兼容客户端使用以下 Base URL：

http://127.0.0.1:9527/anthropic

客户端配置说明：

https://github.com/zentrola/zentrola/blob/main/docs/client-configuration.zh-CN.md⁠

⁠升级

升级前必须：

  1. 阅读 Release Notes。
  2. 同时备份 PostgreSQL 和原始 MASTER_KEY。
  3. 确认新版本的配置及兼容性要求。

拉取并启动新版本：

docker compose pull
docker compose up -d

升级后应检查：

docker compose ps
curl -fsS http://127.0.0.1:9527/health/live
curl -i http://127.0.0.1:9527/health/ready

还应验证管理员登录、Provider 状态以及一次已授权的 Gateway 调用。

⁠安全建议

  • 对外提供服务时，必须通过 HTTPS 暴露 Admin Web 和 Gateway。
  • 不要将 PostgreSQL 和 Redis 暴露到公网。
  • 不要提交包含真实密码或密钥的 compose.yaml。
  • 将数据库密码、Redis 密码、ADMIN_JWT_SECRET 和 MASTER_KEY 分别保存。
  • MASTER_KEY 必须与 PostgreSQL 数据作为同一恢复集备份。
  • 不要在日志、Issue 或截图中公开 Provider Credential、Virtual Key、管理员会话、prompt 或模型输出。
  • 生产环境使用 APP_ENV=prod。
  • CORS 只允许实际使用的 Admin Web Origin。

⁠更多文档

Tag summary

Content type

Image

Digest

sha256:b263b6bcb…

Size

143.8 MB

Last updated

4 days ago

docker pull longjianghu/zentrola