optio

环境要求

• 已安装 git 和 Docker（含 Docker Desktop）
• 本地 Kubernetes 集群（如 Docker Desktop Kubernetes）
• 已安装 Helm（生产部署时需要）
• 生产环境需自备 PostgreSQL 与 Redis，或使用 chart 内置实例
• 生产部署需可用的 Kubernetes 集群和域名/Ingress

安装与启动步骤

1. 1克隆仓库

   把 Optio 源码拉到本地并进入项目目录，后续所有命令都在该目录执行。

   git clone https://github.com/jonwiggins/optio.git && cd optio

   复制

2. 2运行一键安装脚本

   脚本会安装依赖、构建 API/Web/Agent 预设的 Docker 镜像，并通过 Helm 把整套栈部署到本地 Kubernetes，同时安装 metrics-server。耗时较长，请保持网络畅通。

   ./scripts/setup-local.sh

   复制

3. 3访问 Web UI

   打开 http://localhost:30310 进入 Web 界面，API 监听在 http://localhost:30400。Docker Desktop Kubernetes 下这些是 NodePort，需通过 kubectl p

4. 4完成初始化向导

   在 Web UI 的 setup wizard 中依次配置 GitHub 访问、Agent 凭据（API key、OAuth token、Vertex AI 或 Max/Pro 订阅），并添加第一个仓库。

5. 5创建第一个会话

   点击 New session，可选择 Open a PR、Interactive chat、Scheduled run、Persistent agent 等预设，或按五个属性自行组合。

6. 6添加 Helm 仓库(生产)

   生产环境部署时先把 Optio 官方 Helm 仓库加入本地并更新索引，获得最新的 chart 版本。

   helm repo add optio https://jonwiggins.github.io/optio
   helm repo update

   复制

7. 7Helm 安装到集群

   用外部 PostgreSQL 和 Redis 安装到 optio 命名空间，并开启 Ingress。请把数据库、Redis 连接串和域名替换成你自己的真实值。

   helm install optio optio/optio -n optio --create-namespace \
     --set encryption.key=$(openssl rand -hex 32) \
     --set postgresql.enabled=false \
     --set externalDatabase.url="postgres://..." \
     --set redis.enabled=false \
     --set externalRedis.url="redis://..." \
     --set ingress.enabled=true \
     --set ingress.hosts[0].host=optio.example.com

   复制

8. 8从 OCI 仓库安装(可选)

   也可以直接从 GHCR 的 OCI registry 安装 chart，参数与从 Helm 仓库安装一致。

   helm install optio oci://ghcr.io/jonwiggins/optio -n optio --create-namespace \
     --set encryption.key=$(openssl rand -hex 32) \
     --set postgresql.enabled=false \
     --set externalDatabase.url="postgres://..." \
     --set redis.enabled=false \
     --set externalRedis.url="redis://..."

   复制

关键配置

如何确认成功

浏览器打开 http://localhost:30310 能看到 Web UI，说明本地栈部署成功；API 地址为 http://localhost:30400。

常见问题

注意事项

• 快速开始脚本会构建全部 Docker 镜像并部署到本地 Kubernetes，首次执行耗时较长。
• 本地访问 30310/30400 端口通常需要 kubectl port-forward。
• 生产部署务必替换示例中的数据库、Redis 连接串和 Ingress 域名，不要照抄 postgres://... 这类占位值。
• 所有会话、Agent 与代码都运行在你自己的集群和机器上，凭据不出集群。