跳至正文

文档

使用 Docker 自托管 OpenConnector

启动本地 runtime、调用第一个 Action、连接账号，并为部署准备持久化存储和认证。

由 OOMOL 维护·

源码核对日期：2026-09-09. 示例已按链接中的源码版本核对，不代表通过了真实上游 API 验证；你部署的版本可能有所不同。

启动运行环境

需要 Git 和包含 Docker Compose 的 Docker 环境。先调用无需授权的 Action，再配置应用账户。 克隆仓库并启动已发布的镜像。此体验流程用于你自己机器上的本地环境。

Docker
git clone https://github.com/oomol-lab/open-connector.git
cd open-connector
docker compose up

调用第一个 Action

在另一个终端获取 Hacker News 热门文章。此只读 Action 无需服务账户授权。

HTTP · Hacker News
curl -s -X POST \
  http://localhost:3000/v1/actions/hackernews.get_top_stories \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

对本地运行环境调用这个只读、无需服务授权的 Action。若已启用运行时认证，需附带 Bearer 令牌。

连接应用账户

打开本地控制台，选择服务并配置凭证。OAuth 服务需要你在对应平台上注册自己的 OAuth 应用。

凭证与 OAuth →

持久化并保护凭据

Docker 镜像将本地 runtime 数据放在 /app/data，应挂载持久化卷。使用 OOMOL_CONNECT_ENCRYPTION_KEY 加密存储凭据，并妥善保存恢复所需的密钥；公开部署前请阅读部署指南。

公开部署前，需要配置管理端认证、运行时令牌、凭证加密和 OAuth 公网地址。生产环境设置请遵循部署指南。

完整部署指南 ↗

对外部署前的准备

项目的 Compose 文件将 connector-data 挂载到 /app/data。允许远程访问前，应分别设置 OOMOL_CONNECT_ADMIN_TOKEN、OOMOL_CONNECT_RUNTIME_TOKEN，并设置 OOMOL_CONNECT_ENCRYPTION_KEY。配置公开访问地址，在部署入口启用 HTTPS，不要将密钥提交到版本库。

升级与恢复准备

记录部署的镜像版本，备份运行时数据库，并安全保管对应的加密密钥副本。升级前在隔离环境验证恢复过程。密钥丢失后无法恢复加密记录；删除数据卷会删除本地数据库。

理解调用结果

HTTP 运行时响应包含 success、message、data 和 meta。请检查 success 及 Action 输出 Schema，不要只看 HTTP 状态码。执行元数据包含 executionId 时，可据此定位脱敏运行日志。下面仅展示响应结构，并非真实 API 调用结果。

示意响应
{
  "success": true,
  "message": "OK",
  "data": {},
  "meta": {}
}

调用失败时如何排查

  • 认证失败时，先核对接口和凭证类型：管理端凭证用于 /api，运行时 Bearer 令牌用于 /v1 和 /mcp。服务提供方的 API Key 不能替代运行时令牌。
  • 权限被拒绝时，检查 Action 所需 scopes、运行时 Action 规则和连接授权。令牌有效也不代表有权使用所选账号。
  • 结果为空或资源缺失时，检查连接账号及其对目标资源的访问权限。完成授权不代表能访问所有工作区、频道或文档。
  • 重试前先检查错误与运行日志。对于会修改服务数据的 Action，先确认操作是否已经完成，不要盲目重复请求。
阅读 Markdown