从头到尾搭建并运行你自己的 Contextify Cloud 服务器。

最快的方式

让 AI 帮你配置

你已经在用编程智能体了。把这份运行手册交给它，它会替你部署服务器：在你的 shell 中逐条运行命令，并在关键选择处暂停询问你。所有操作都在你的机器上运行。

把这段提示词粘贴给 AI

把这段提示词复制到 Claude Code、Codex 或任意编程智能体中。它会引导智能体读取一份我们持续更新的运行手册，因此提示词本身可以保持简短、稳定。

Help me set up a self-hosted Contextify server on this machine. Read the runbook at https://contextify.sh/docs/self-hosted/agent-setup.md and follow it exactly: run the commands in my shell, show me what you are doing, generate any secrets locally on this machine, and pause to ask me at every step marked [ASK ME]. When it is done, verify the server is healthy and my Contextify app can search across it.

复制提示词

运行手册位于 contextify.sh/docs/self-hosted/agent-setup.md。如果你的智能体无法获取 URL，请打开该链接，把内容粘贴到对话中。

即将推出：如果你在 Claude Code 或 Codex 中使用 contextify CLI，内置的配置技能（skill）会把这一过程简化为一条命令。它将在未来的 Contextify 版本中发布；在此之前，请使用上面的提示词。

自己动手

开始之前

想手动运行，或者想确切了解智能体会做什么？下面就是同样的 4 个步骤，从头到尾。

第 1 步：运行服务器

克隆公开源码，并根据示例创建环境文件：

git clone https://github.com/PeterPym/contextify-cloud-self-hosted.git
cd contextify-cloud-self-hosted
cp .env.example .env

在 .env 中填写密钥和 URL

在 shell 中生成 3 个机密值，并把每个值复制到 .env 中。不要把 $(...) 命令粘贴进文件：Docker Compose 按字面读取 .env，不会执行命令，所以一行 $(openssl ...) 会原样成为你的实际密钥。

openssl rand -hex 32    # copy into API_SECRET_KEY
openssl rand -hex 20    # copy into DB_PASSWORD
openssl rand -hex 32    # copy into CONTEXTIFY_SELF_HOSTED_SETUP_TOKEN

然后编辑 .env，填好以下各项：

这个 Compose 文件会忽略 .env.example 中的 DATABASE_URL 这一行，并根据 DB_PASSWORD 自行构建连接字符串，所以你无需编辑它。登录使用密码，因此邮件服务商是可选的：将 RESEND_API_KEY 留空，认证邮件会写入服务器日志，而不是发送出去。

启动服务栈

docker compose -f docker-compose.selfhosted.yml up -d --build

首次运行会构建 API 镜像，在小型机器上需要几分钟。用 docker compose -f docker-compose.selfhosted.yml ps 查看进度。API 默认绑定到回环地址（127.0.0.1:8443）；第 2 步会在它前面加上 HTTPS。

确认服务器状态正常

curl -s http://127.0.0.1:8443/api/v1/health

状态正常的自托管服务器会返回：

{"status": "ok", "self_hosted": true}

所有者账号在第 2 步创建，届时真实主机名和 HTTPS 已经就绪，这样配置链接会指向各台机器实际使用的地址。

第 2 步：保护服务器

API 监听一个回环端口；你通过稳定的主机名和匹配的 TLS 证书，以 HTTPS 访问它。推荐方式是 Tailscale HTTPS：它在回环 API 端口前加上 HTTPS，使用只在你的私有 tailnet 内可达的 .ts.net 主机名，因此服务器永远不会暴露到公共互联网。证书所证明的主机名，就是你在 Contextify 中配置的主机名。用你自己的反向代理公开暴露服务器属于高级选项，TLS、认证和限流加固都由你负责；除非有明确的理由，否则请保持私有。

阅读 TLS、VPN 和 Tailscale 指南

让配置与最终 URL 保持一致

HTTPS 就位后，确认服务器的配置与这个源（origin）完全一致：

• 检查 URL 变量

  确认 .env 中的 ALLOWED_ORIGINS、EMAIL_BASE_URL 和 INVITATION_BASE_URL 都与最终的 HTTPS 源一致。

• 开启安全 Cookie

  在 .env 中设置 FORCE_SECURE_COOKIES=true。示例文件中它的值为 false，用于本地 HTTP 验证。

• 应用更改

  重新运行 docker compose -f docker-compose.selfhosted.yml up -d，让容器读取更新后的环境变量。

创建所有者账号

Personal Self-Hosted 是单用户方案；第一个账号就是服务器的所有者。请通过实际使用的 HTTPS 主机名创建该账号，且只创建一次。你可以在浏览器中打开一次性配置页面：

https://your-server.example.ts.net/setup?token=YOUR_SETUP_TOKEN

或者，对于无图形界面的服务器，从命令行创建所有者：

docker compose -f docker-compose.selfhosted.yml exec api \
  python -m contextify_cloud create-admin --email you@example.com

第 3 步：让 Contextify 指向服务器

服务器运行并可访问后，连接你的机器。使用服务器 URL，以及在仪表盘中创建的、具备同步权限的 API 密钥。

阅读完整的连接教程

如果服务器只能在 VPN 或 tailnet 内访问，请在该网络中的设备上运行连接命令。

第 4 步：验证搜索和找回

在一台已连接的机器上，确认整个往返流程端到端正常。

• 确认同步

  运行 contextify cloud status --json，检查最近的项目是否已同步。你也可以在服务器 URL 打开只读仪表盘。

• 搜索历史记录

  在 Mac 应用或仪表盘中，搜索一个你确定出现在过往会话中的词。结果来自你运维的服务器。

• 在 AI 助手中找回

  用 Total Recall（跨会话历史检索）把过去的决策、修复或调试会话带入当前工作：在 Claude Code 中使用 /total-recall，在 Codex 中使用 $total-recall。

继续阅读