自托管 Cloud
连接到你自己的 Contextify Cloud 服务器。
如果你希望同步 API 和仪表盘运行在自己掌控的基础设施上，可以选择自托管 Cloud。服务器就绪后，客户端配置很简单：使用服务器 URL 和支持同步的 API 密钥。
本页介绍如何把客户端连接到已有的自托管服务器。如需从零搭建服务器，请参阅自托管配置指南。该指南会带你完成运行 Docker 服务栈、保护服务器、连接 Contextify，以及验证搜索和找回。
准备工作
服务器 URL
使用客户端能访问到的服务器 URL，包括正确的协议和端口。对于只通过 Tailscale 或 VPN 访问的配置，它可能是 tailnet 主机名，而不是公网地址。
API 密钥
在自托管仪表盘中创建具备同步权限的 API 密钥。仅有搜索权限的密钥不能用于上传。
健康检查
配置客户端之前，服务器应能在 /api/v1/health 正常响应。
确认服务器状态正常
在能访问服务器的设备上，请求健康检查端点：
curl -s https://your-server.example.com/api/v1/health状态正常的自托管服务器会返回：
{"status": "ok", "self_hosted": true}
在自托管部署中，self_hosted 为 true；在托管版 Contextify Cloud 上为 false。你可以借此确认所指向的 URL 正是预期的服务器。
连接 Mac 应用
-
打开“Settings → Cloud”（云端设置页）
选择 Contextify Cloud Self-Hosted。
-
输入服务器 URL
使用服务器 TLS 证书所覆盖的同一主机名。如果使用 Tailscale HTTPS，这通常是一个
.ts.net主机名。 -
粘贴 API 密钥
应用会先验证自托管服务器和 API 密钥，然后才替换这台 Mac 上已保存的托管版连接。
-
保存并查看状态
Cloud 标签页应显示自托管提供方、服务器 URL 和同步状态。如果应用仍在导入大量本地历史记录，同步可能要等本地处理完成后才开始。
通过 CLI 连接
尽量使用交互式提示输入，这样 API 密钥不会留在 shell 历史中。
contextify cloud setup --url https://your-server.example.com
contextify cloud status --json
contextify cloud sync
无图形界面的配置可以使用 --key。如果命令的终端记录中包含真实密钥，请把它当作敏感信息处理。
contextify cloud setup --url https://your-server.example.com --key ctx_REDACTED --no-input如果自托管服务器只能在 VPN 或 tailnet 内访问，请在该网络中的设备上运行这些命令。
服务器配置简介
自托管服务器使用 Docker Compose 运行 contextify-cloud Docker 服务栈和 PostgreSQL，并启用 SELF_HOSTED=true。自托管配置指南完整介绍了部署过程：克隆公开源码、填写密钥、启动服务栈以及创建所有者账号。
受支持的 HTTPS 配置需要网络中一个稳定的主机名，由 API 前端的反向代理终止 TLS，再将请求转发到 API 的容器回环端口。仅使用 HTTP 的模式可用于在可信网络中验证，但不适合作为推荐的长期配置。
常见的首次失败
自托管最常见的连接问题是目标主机不可达：Mac 虽能上网，却无法解析自托管服务器的主机名，或无法连接该主机。
如果连接正常但 Cloud 尚未同步完成，请阅读导入与同步说明。
最后更新：2026 年 5 月 6 日