部署指南

Arkloop 提供两种自部署入口：

• 推荐：./setup.sh install，自动完成参数归并、pre-flight、.env 补全与默认模块启动
• 底层：compose.yaml，适合手动调试或细粒度控制

服务总览

默认启动顺序由 depends_on 保证：postgres → migrate → api/worker，redis → api/gateway/worker。启用可选 profile 时，pgbouncer、seaweedfs、openviking、docker-sandbox、firecracker、console-full 等模块会按需加入。

快速开始

1. 推荐：用 setup.sh 安装

./setup.sh install

setup.sh 会完成这些事情：

• 统一解析交互问答、CLI flags 与默认值
• 检查 Docker、Compose、端口占用、KVM 与 Docker socket
• 复制并补全 .env，自动生成缺失密钥
• 按模块选择启动 compose.yaml 中的目标服务
• 等待健康检查通过，并打印入口地址

如果要给 Agent 或 CI 使用非交互安装：

./setup.sh install \
  --profile standard \
  --mode self-hosted \
  --memory none \
  --sandbox none \
  --console lite \
  --browser off \
  --web-tools builtin \
  --gateway on \
  --non-interactive

2. 底层：直接使用 Compose

cp .env.example .env
docker compose up -d postgres redis migrate api worker console-lite gateway

如果要启用完整 Console，再叠加 profile：

docker compose --profile console-full up -d console gateway

migrate 服务会自动在 api/worker 启动之前运行迁移并退出。查看启动状态：

docker compose ps

3. 访问服务

默认情况下，内部服务只在 Docker 网络内暴露。如果需要宿主机调试端口，请显式叠加开发覆盖文件：

docker compose -f compose.yaml -f compose.dev.yaml up -d

平台管理员初始化

首次部署时，可以通过环境变量把指定用户提升为 platform_admin（一次性执行）。

步骤：

1. 先注册/登录一个账号
2. 调用 GET /v1/auth/me 获取 id
3. 在 .env 中设置：

ARKLOOP_BOOTSTRAP_PLATFORM_ADMIN=<user_id>

然后重启 api 服务。

Tool Providers（可选）

web_search / web_fetch 等工具需要配置后端 Provider 与凭证。

推荐方式（SaaS / 自托管通用）：

• 用 bootstrap 的 platform_admin 登录 Console
• 在 Tool Providers 中使用 scope=platform 配置一次作为全局默认
• 如需单个租户自定义，再用 scope=org 覆盖

兼容方式（仅用于本地快速跑通）：

• 直接用环境变量配置 legacy web_search.* / web_fetch.*（例如 ARKLOOP_WEB_SEARCH_PROVIDER、ARKLOOP_WEB_SEARCH_TAVILY_API_KEY）

查看日志

# 所有服务
docker compose logs -f
 
# 单个服务
docker compose logs -f api
docker compose logs -f worker
docker compose logs -f gateway

重新部署（更新代码后）

docker compose build api worker gateway
docker compose up -d

迁移会在 api 启动前自动重新执行。若需强制重跑迁移：

docker compose run --rm migrate up

停止 / 清理

# 停止，保留数据
docker compose down
 
# 停止并清除数据卷（重置数据库）
docker compose down -v

Sandbox rootfs 构建

Sandbox 服务使用 Firecracker microVM 执行用户代码，需要预构建 rootfs ext4 镜像。

构建 rootfs

cd src/services/sandbox/rootfs
./build.sh

构建产物输出到 src/services/sandbox/rootfs/output/python3.12.ext4。

部署到目标机器

DEPLOY_HOST=user@host ./build.sh

默认部署路径为 /opt/sandbox/rootfs/，可通过 DEPLOY_PATH 覆盖。

预装环境

修改预装内容：编辑 src/services/sandbox/rootfs/Dockerfile.python3.12 后重新构建。

Sandbox 部署

Sandbox 支持两种后端 Provider，通过 sandbox.provider 配置项（或 ARKLOOP_SANDBOX_PROVIDER 环境变量）切换。

Firecracker 模式（默认）

Linux + KVM 环境，使用 microVM 隔离：

docker compose --profile firecracker up -d sandbox

需要 /dev/kvm 设备和 Firecracker 二进制。

推荐保持最小权限运行，不再要求 privileged。

Docker 模式

macOS / Windows (WSL2) / 无 KVM 环境，使用 Docker 容器隔离：

# 指定用户态 Docker socket
export ARKLOOP_SANDBOX_DOCKER_SOCKET_PATH=/run/user/1000/docker.sock
 
# 启动
docker compose --profile docker-sandbox up -d sandbox-docker

Compose 默认会使用 src/services/sandbox/Dockerfile.agent 构建本地 sandbox-agent 镜像，并打上 arkloop/sandbox-agent:dev 标签。

Linux 推荐使用 rootless Docker 的用户态 socket。 macOS / Windows Docker Desktop 请改为各自用户目录下的 socket 路径，不再使用系统级 /var/run/docker.sock。

sandbox-docker 自身运行在 Compose 网络中，派生出的 sandbox-agent 容器按策略接入专用网络，不使用 host 网络。启用外网时使用 arkloop_sandbox_agent_egress，禁用外网时使用 arkloop_sandbox_agent_internal；如需切换，可设置 ARKLOOP_SANDBOX_ALLOW_EGRESS 并重建网络。

Docker backend 镜像内置常用开发命令，包括 git、curl、wget、jq、grep、rg、find、tar、zip、unzip、sqlite3、ssh、make 等，保证终端型任务和仓库分析任务可直接运行。

本地开发（直接运行）

cd src/services/sandbox
go build -o sandbox-bin ./cmd/sandbox
 
# Docker 模式
ARKLOOP_SANDBOX_PROVIDER=docker \
DOCKER_HOST=unix:///run/user/1000/docker.sock \
ARKLOOP_SANDBOX_SOCKET_DIR=/tmp/sandbox \
ARKLOOP_SANDBOX_TEMPLATES_PATH="" \
./sandbox-bin

Sandbox 配置

运行时参数通过 Console > Configuration > Sandbox 页面配置（写入 platform_settings 表），也可用环境变量覆盖：

部署级参数（仅 ENV，不进 Console）：

本地开发模式

开发时通常希望在宿主机运行 API（便于调试/热更新），只用 Docker 跑基础设施：

# 只起基础设施
docker compose -f compose.yaml -f compose.dev.yaml up -d postgres redis
 
# 如需验证可选性能层
docker compose -f compose.yaml -f compose.dev.yaml --profile performance up -d pgbouncer redis_gateway
 
# 如需验证可选对象存储
docker compose -f compose.yaml -f compose.dev.yaml --profile s3 up -d seaweedfs
 
# 运行迁移
cd src/services/api
ARKLOOP_LOAD_DOTENV=1 ARKLOOP_DOTENV_FILE=../../.env go run ./cmd/migrate up
 
# 在宿主机运行 API
ARKLOOP_LOAD_DOTENV=1 ARKLOOP_DOTENV_FILE=../../.env go run ./cmd/api

此时如需使用 Gateway，覆盖 upstream 指向宿主机：

ARKLOOP_GATEWAY_UPSTREAM=http://host.docker.internal:19001 docker compose -f compose.yaml -f compose.dev.yaml up -d gateway

完整环境变量参考

数据库

Redis

存储

对象存储（可选 SeaweedFS / S3 兼容）

鉴权与加密

API

Gateway

Worker

Telegram Channel

Webhook 由 API 接收入站；无公网时用 Desktop 轮询 getUpdates，链路仍落到同一套 run / mw_channel_delivery。channels.config_json 可设 telegram_typing_indicator（默认 true）、telegram_reaction_emoji（空则关闭；非空则在投递成功后对用户入站消息点表情）。

调试