capka

# 卡普卡 🐾 [](LICENSE) [](#预构建镜像) [](https://capka.yuri.ly/) 您好，我正在构建 **卡普卡** ，因为我找不到一个像样的开源 Web UI，它能将 AI 视为一个真正的 *代理* ，而不仅仅是一个聊天机器人。 将其视为 **克劳德工作台的开源、自托管版本** —— 一个具有自己的计算机的代理，而不是一个聊天框。大多数 AI UI 只是围绕 API 的薄包装。卡普卡为每个用户和每次聊天提供一个 **隔离的 Linux 沙盒**：代理接受文件，编写和运行代码，爬取网页，转换文档，并使用 MCP 连接器 —— 安全地，在其自己的容器中，背后是您自己的 API 密钥。  > 🌐 **尝试在线演示 → [capka.yuri.ly](https://capka.yuri.ly/)** —— 在您自己的主机之前，先探索一个正在运行的实例。 > 💡 **名字由来？** *卡普卡* （读音 *[tsap-ka]* 或简称 "cap-ka"）来自乌克兰语 *цап-царап* ，意为猫爪的快速挥动 —— 是的，那是标志。我喜欢这个图案：一个代理，抓取您的文件并直接深入其中。 ## 为什么我要构建它 互联网上充斥着周末项目聊天应用，它们看起来很相似，无法处理真正的任务，或者向用户泄露原始 JSON 错误。我想要一个可以在廉价 VPS 上为自己、朋友和团队托管的运行时。 丢进一个文件然后询问 —— 卡普卡在沙盒中运行真正的工具（`ffprobe`、`ffmpeg` 等）并返回结果：  您将获得： - **真正的隔离** —— 代码执行和文档工作在每个会话的 Docker 容器中运行（Python 3.12、Node 22、Java、FFmpeg、ImageMagick、LibreOffice、LaTeX、Playwright、OCR 等）。代理永远不会触及主机。 - **它不会忘记** —— 每个回合都是一个独立的任务，基于 Postgres 的队列，由进程内工作器运行。关闭笔记本或重启服务器，代理将继续运行 —— 回复不会丢失。 - **没有 "AI 混乱" 的用户体验** —— 我亲自优化了 UI，以感觉像一个真正的、经过考虑的工具。提供商超时和速率限制被捕获并转换为平静的本地化消息 —— 最终用户永远不会看到原始 `402`。 - **可扩展** —— 与 Anthropic 兼容的技能、MCP 连接器（包括 OAuth）和一个小型市场，具有每个功能的允许/询问/拒绝治理和审计日志。 ## 它是如何在幕后工作的 一个扁平、高效的架构，因此易于自托管 —— 即使在一个盒子上。 | 服务 | 它是什么 | |---|---| | **平台** | Next.js 应用 + 进程内任务工作器（UI、API、代理循环）。 | | **Postgres** | 大脑：记录系统 **和** 实时任务队列（`LISTEN/NOTIFY`）。 | | **沙盒控制器** | 一个小型 HTTP 服务，负责启动/停止每个会话的容器。它通过套接字代理访问 Docker，绝不直接访问原始套接字 —— 由 `CONTROLLER_SECRET` 保护。 | | **套接字代理** | Docker API 的防火墙：仅限容器 + 执行端点。主机套接字在此处以只读方式挂载，位于隔离的网络中。 | | **沙盒** | 执行镜像（`Dockerfile.sandbox`）—— 构建一次，按需重用每个会话。 | > ⚠️ **如果您想贡献，请注意：** 该项目运行在高度自定义的 **Next.js 16** 上。由于进程内工作器循环，它 **不是** 一个标准的 Next.js 应用 —— 请阅读 `AGENTS.md` 并检查 `node_modules/next/dist/docs/` 在修改框架内部之前。 ## 入门指南（本地开发） 零配置 —— 开发 compose 文件使用环回端口和开发密钥，因此无需编写 `.env` 文件： ```bash npm run docker:dev ``` 打开 http://localhost:3000 并创建管理员帐户。 ## 部署（生产） 在全新 Linux 盒上，一条命令安装 Docker（如果缺少），获取卡普卡，并使用自动 HTTPS（通过 Caddy）启动完整堆栈 —— 请先将 DNS 指向主机： ```bash curl -fsSL https://raw.githubusercontent.com/LyoSU/capka/master/install.sh | DOMAIN=capka.example.com sh ``` 没有域名？您仍然可以免费获得 HTTPS：安装程序提供一个基于服务器公网 IP 的主机名，通过 [sslip.io](https://sslip.io) （`<ip>.sslip.io` 直接解析到 IP，因此 Caddy 获取真正的 Let's Encrypt 证书 —— 无需设置 DNS）。交互式运行，它建议此作为默认值；通过管道，它打印确切的 `DOMAIN=…sslip.io` 命令以重新运行。或者完全省略 HTTPS，它直接提供纯 `:3000` 给您的自定义反向代理。更倾向于在运行前阅读？好习惯： ```bash curl -fsSL https://raw.githubusercontent.com/LyoSU/capka/master/install.sh -o install.sh less install.sh && sh install.sh ``` 已经有 Docker 和克隆？安装程序只是包装此： ```bash git clone https://github.com/LyoSU/capka && cd capka DOMAIN=capka.example.com ./scripts/up.sh # 或：npm run up ``` `up.sh` 在首次运行时生成强密钥到 `.env` （它从不覆盖您设置的值），拉取预构建的镜像，然后启动堆栈。重新运行安装程序会升级到位（`git pull` + 镜像刷新）。 > 卡普卡作为一个 **长期运行的进程** —— 无服务器/边缘主机在请求之间冻结不会工作。 ### 服务器要求 卡普卡几乎可以在任何地方运行：任何具有 Docker 的 Linux 主机，**x86_64 或 arm64** （预构建镜像是多架构的，因此廉价的 ARM VPS 也适用 —— 主机拉取其原生架构，无需本地编译）。 | | CPU | RAM | 磁盘 | |---|---|---|---| | **最低** | 1-2 vCPU | 2 GB | 20 GB | | **推荐** | 2 vCPU | 4 GB | 40 GB | 入门级 VPS 可以舒适地运行完整堆栈 —— 当前价格约为 7 美元/月（例如 Hetzner CX23 或 ARM CAX11）。磁盘主要由沙盒镜像占用（~7.5 GB）；拉取预构建镜像意味着主机上没有 RAM 饥饿构建。更重或多并发用户工作负载需要更多 RAM 和 [gVisor](#安全与沙盒) 硬化。 ### 哪条路径适合我？ | 您的设置 | 执行此操作 | |---|---| | 只是测试（无沙盒） | 一键 PaaS：**Railway** (`deploy/railway.json`) 或 **Fly.io** (`deploy/fly.md`) —— *仅限平台，无 Docker 守护进程 → 无代码沙盒*。 | | 独自/小型团队在 VPS 上 | `DOMAIN=… npm run up` （开箱即用的 HTTPS），或一键 **Coolify** (`deploy/coolify.md`) —— 部署到具有 Docker 守护进程的主机，因此您获得 **完整堆栈，包括沙盒**。 | | 更高的信任/公司 | 外部托管 Postgres，无根 Docker，SSO —— 请参阅 `SECURITY.md`。 | ### 机密 `npm run up` 为您生成这些，或者您自己设置它们（请参阅 `.env.example`）： - `POSTGRES_PASSWORD` —— Postgres 密码；`DATABASE_URL` 从中派生。 - `CONTROLLER_SECRET` —— 平台↔控制器的共享密钥。控制器在默认值上 **拒绝启动** —— `openssl rand -hex 32`。 - `CAPKA_MASTER_KEY` —— 64-十六进制密钥，用于静止加密提供商 API 密钥，保存在数据库之外，因此数据库泄漏无法单独解密它们。 - `PUBLIC_URL` *(可选)* —— 您的公共源；未设置 → 从代理标头派生。 在代理后面设置它（这是身份验证回调和绝对链接的不可伪造源）。 ### 预构建镜像 发布标签将 `平台`、`控制器` 和 `沙盒` 镜像发布到 GHCR (`ghcr.io/lyosu/capka-*`)，因此没有构建工具链的主机不会编译任何内容 —— `up.sh` 默认拉取它们。 `build:` 语句保留为后备：如果拉取失败（离线，或您处于未发布的提交），则受影响的镜像会本地构建。要始终从源代码编译： ```bash CAPKA_BUILD=1 ./scripts/up.sh ``` ### 更新 **设置 → 更新** （管理员）显示正在运行的版本与最新版本，附带更改日志和一行更新命令；当您落后时，会出现横幅。检查结果会被缓存，可以关闭（无需外出调用）。卡普卡无法从其沙盒容器内部重启，因此更新是主机操作： ```bash cd /opt/capka && sudo ./scripts/update.sh # 获取最新版本，拉取镜像，重新创建 ``` 它保留您的 `.env` 和数据，并将镜像标签固定到它检查的代码。 ## 安全与沙盒 开箱即用，沙盒在标准的 `runc` 运行时（在任何 Docker 主机上都起作用）上运行。容器是无特权的（入口点降级到 `1000:1000`）并丢弃所有功能。沙盒互联网访问在管理员面板中管理（**安全 → 互联网访问**），并且在启用时，防火墙阻止私有范围和云元数据。这是纵深防御；对于真正的“逃逸 ≠ 主机 root”边界，请运行一个 **无根** Docker 守护进程。 对于不受信任或多租户工作负载，请选择 **gVisor** —— 一个具有更强的容器↔主机边界的用户空间内核，无需 KVM（因此它在普通 VPS 主机上运行）： 1. 在主机上：`sudo sh scripts/install-gvisor.sh`，然后重启 Docker。 2. 设置 `SANDBOX_RUNTIME=runsc` 并重新部署。 然后它是 **关闭失败** 的 —— 如果 `runsc` 未注册，控制器拒绝启动，绝不会静默降级为 `runc`。请参阅 **[`SECURITY.md`](SECURITY.md)** 以获取完整的安全威胁模型和无根设置，然后再向不受信任的用户公开卡普卡。 ## 首次运行 1. 打开应用 → 您将进入 **`/setup`** 以创建管理员帐户。 2. **设置 → 连接** —— 添加 AI 提供商密钥（Anthropic、OpenAI、OpenRouter、Ollama 等）并选择默认模型。 3. 默认情况下，注册是 **仅限邀请** 的 —— 从管理员面板添加您的朋友/团队。 4. *(奖励)* **设置 → 集成** —— 添加 Telegram 机器人令牌，并通过相同的持久沙盒引擎与同一个代理从 Telegram 聊天。 ## 开发脚本 ```bash npm run dev # Next.js 开发服务器（需要外部 Postgres via DATABASE_URL） npm run docker:dev # 具有开发默认值的完整堆栈（推荐） npm run up # 生产环境：生成 .env 中的密钥（如果需要），然后启动 npm run docker:prod # 构建 + 运行分离（密钥已设置） npm run docker:down # 停止堆栈 npm run sandbox:build # （重新）构建沙盒执行镜像 npm test # vitest 单元测试（集成测试在 RUN_INTEGRATION=1 后启用） ``` 编辑工作器、运行器、仪表板或 Telegram 机器人后，请重启平台容器 —— HMR 不会重载进程内工作器循环。 ## 许可证 卡普卡在 **GNU AGPL-3.0** 下开源（参见 `LICENSE`）。自行托管、修改、分享 —— 如果您将其作为公共网络服务运行，AGPL 的源代码可用性条款适用。 我主要独自构建此项目。一些企业功能（SSO/OIDC 和 SCIM，高级 RBAC，Helm 打包）存在于单独的版本中 —— 如果您的公司需要它们，请联系我们。贡献非常受欢迎，并经过快速的 **贡献者许可协议** —— 请参阅 `CONTRIBUTING.md`。