Oratorio

简体中文

English

简体中文

English

外观

服务器部署 ​

服务器部署指在一台 Linux 主机上持续运行一套专用的 Oratorio 后端和 DotCraft AppServer，用于无人值守的 source sync、PR review dispatch 和 draft generation。推荐入口是 Oratorio CLI。

bash
curl -fsSL https://dotharness.github.io/oratorio/install.sh | bash
oratorio server init

安装脚本会从 GitHub Releases 下载 Linux x64 的 oratorio CLI，并校验 release checksum。之后由 CLI 创建和管理 Docker Compose review stack。

CLI 会创建什么 ​

oratorio server init 会创建一套独立 review stack：

text
oratorio-review/
  docker-compose.yml
  docker-compose.webhook.yml  # 仅在启用公网 Webhook ingress 时生成
  Caddyfile                   # 仅在启用公网 Webhook ingress 时生成
  .env
  oratorio.config.json
  workspace/
  secrets/

这套 stack 包含：

  • 一个 Oratorio backend container；
  • 一个专门用于 review 工作的 DotCraft AppServer container；
  • 一个被两个 container 共同挂载的 /workspace；
  • 一个由 CLI 管理的 server-side oratorio.config.json。
  • 一个可选的 Caddy gateway，只公开 GitHub Webhook endpoint。

这套 review stack 默认和你已有的 QQ 机器人、聊天机器人或其他业务 DotCraft container 隔离。

核心约束：共享文件系统 ​

Oratorio 会创建 Git worktree，并把 worktree 的绝对路径交给 DotCraft。 因此 Oratorio 和 DotCraft 必须在同一个绝对路径下看到同一份 workspace。 CLI 生成的 stack 会把宿主机 workspace/ 同时挂到两个 container 的 /workspace。

多个仓库不需要多个 container。一套 stack 可以通过多条 workspace route review 多个仓库：

bash
oratorio server add-repo github:owner/repo-a
oratorio server add-repo github:owner/repo-b

每个仓库会 clone 到 workspace/<owner>__<repo>，并在 oratorio.config.json 中映射到 /workspace/<owner>__<repo>。

首次运行 ​

oratorio server init 会依次询问：

  • DotCraft provider、model 和 API key；
  • 一个或多个 GitHub repository；
  • GitHub App ID 和 private key path 或 file；
  • 可选的 repository owner 对应 GitHub App installation ID；
  • 是否开启 Auto Review；
  • 是否开启 GitHub write-back。
  • 可选的 GitHub Webhook 公网 DNS name 或 IP address。

CLI 会使用服务器上已有的 Git 凭据执行 git clone；它不会把 GitHub API App installation token 写进 Git remote。GitHub App 是 GitHub API authentication 的唯一支持方式，覆盖 read sync、PR review、checks、comments 和 delivery。若希望 App 只读，可使用 --no-github-writes。

Stack 启动后，CLI 会输出 SSH tunnel 命令：

bash
ssh -N -L 5087:127.0.0.1:5087 user@your-server

在 Oratorio Desktop 中，可以使用 远端 > SSH tunnel 并选择本机 SSH config 里的 alias（例如 your-server）；也可以手动打开 tunnel 后使用 远端 > URL。 tunnel 后的 backend URL 是：

text
http://127.0.0.1:5087

Desktop tunnel 模式使用系统 ssh 和本机 SSH config、key 或 agent；不会保存 SSH 密码或私钥内容。

启用 GitHub Webhook ingress ​

当 GitHub 需要投递评论命令或同步事件时，保持 backend 私有，并添加 HTTPS gateway：

bash
oratorio server webhook enable \
  --public-host webhooks.example.com \
  --acme-email ops@example.com

该命令会生成 docker-compose.webhook.yml 和 Caddyfile，向 .env 写入 32-byte Webhook secret，检查 80、443 端口，验证两份 container 配置并启动 gateway。Oratorio 会被重建以读取 secret。新生成的 secret 只显示一次。若要使用 已经生成的 secret，请把单行值放在文件中：

bash
oratorio server webhook enable \
  --public-host webhooks.example.com \
  --secret-file ./webhook-secret.txt

也可以在初始化时直接启用 ingress：

bash
oratorio server init --webhook-public-host webhooks.example.com

交互式初始化允许把 host 留空，从而保持私有部署。非交互 --yes 模式只有在 显式传入 --webhook-public-host 时才会启用 ingress。

DNS name 使用 Caddy 常规 automatic HTTPS。也可以填写可全局路由的公网 IP； 此时 Caddy 会使用 Let's Encrypt shortlived ACME profile 申请证书，并通过 持久化 certificate volume 自动续期。Private、loopback、link-local、reserved 地址以及 URL 形式的输入都会被拒绝。

公网 URL 为：

text
https://<host-or-ip>/api/v1/sources/github/webhook

Gateway 只转发该路径的精确 POST。GET、相邻路径、health check 和其他所有 /api/v1/* 路径都会直接返回 404。

CAUTION

在主机和云防火墙中允许入站 TCP 80 和 443，但不要开放 5087、 AppServer port 或 dashboard port。80 只用于 ACME validation 和 HTTPS redirect，不提供 HTTP Webhook fallback。

CLI 不会修改 DNS、firewall rule 或 GitHub App 设置。请在 GitHub App 中手工 启用 Webhook、粘贴 CLI 显示的 secret、保持 SSL verification 开启，并订阅 Issue comments。完整清单见 GitHub 集成。

日常运维 ​

常用命令：

bash
oratorio server doctor
oratorio server status
oratorio server logs --follow
oratorio server restart
oratorio server upgrade
oratorio server webhook status

doctor 会检查 Docker、Docker Compose、Git、必要 secret、仓库 checkout、 workspace route 和 Oratorio health。启用 ingress 后，它还会验证合并后的 Compose model、Caddyfile、gateway container、secret 是否存在，以及 80、 443 是否正在监听。诊断不会显示 secret 值。

status、logs、restart 和 upgrade 会在 overlay 存在时自动使用合并后的 Compose 配置。只关闭公网 ingress：

bash
oratorio server webhook disable

Disable 会停止并移除 gateway 及其 CLI-managed 文件，但保留 Webhook secret、 Caddy certificate volume、Oratorio、DotCraft 和 SSH tunnel 访问。

配置归属 ​

服务器部署下，配置由服务器侧 CLI 和文件管理：

  • .env 存放模型 key、AppServer token 等 secret；
  • secrets/ 存放 GitHub App private key 等挂载文件；
  • oratorio.config.json 存放 source list、workspace route 和 automation policy； 也包含 GitHub App ID、private key path、writes 设置和可选 installation profile；
  • Oratorio Desktop remote mode 只读展示 server-admin 配置。

CLI 生成的 Docker stack 会设置 Oratorio:Settings:Writable=false，所以即使 SSH tunnel 让请求看起来来自 loopback，Desktop 也不能误写 server-admin 配置。

手动 Compose 配置 ​

高级用户仍可手动使用 Compose 模板：

bash
mkdir oratorio && cd oratorio
curl -O https://raw.githubusercontent.com/DotHarness/oratorio/master/deploy/docker/docker-compose.yml
curl -O https://raw.githubusercontent.com/DotHarness/oratorio/master/deploy/docker/.env.example
cp .env.example .env

如果要配置多个仓库，优先使用 oratorio.config.json，不要手写很长的 environment variable 数组。

若要手工配置基于 DNS 的 Webhook gateway，还需下载 docker-compose.webhook.yml 和 Caddyfile，替换示例 DNS name，在 .env 中设置 ORATORIO_GITHUB_WEBHOOK_SECRET，然后验证并启动合并后的 stack：

bash
docker compose \
  -f docker-compose.yml \
  -f docker-compose.webhook.yml \
  config --quiet
docker compose \
  -f docker-compose.yml \
  -f docker-compose.webhook.yml \
  up -d

公网 IP ingress 请使用 CLI，以确保生成所需的 short-lived certificate policy。

延伸阅读 ​

Apache License 2.0

Copyright © DotHarness