跳转到内容
艺爪编程文档
官网

安装服务端

服务端是整套系统的中心：存任务、对话、附件、代码库配置、权限、凭据和审计，并把执行类操作路由到各台电脑。它跑在一台长期开机的 Linux 或 macOS 上，用 Docker 运行。

一行安装

Linux（Ubuntu 24.04）或 macOS（Apple Silicon + OrbStack）：

Terminal window
curl -fsSL \
  https://code.ezboti.com/install.sh \
  | sh

脚本会：

  • 检查 Docker / Compose；Linux 没装时自动安装；
  • 从腾讯云镜像仓库拉取服务端、PostgreSQL 17、Meilisearch、Gitea 等镜像；
  • 首次生成数据库口令、主密钥、Gitea 口令和登录码，写入数据目录的 .env（0600）；重跑只复用，不重新生成；
  • 启动容器，打印访问地址（终端显示 Access URL）和 8 位登录码。

Linux 默认包含自托管 Git（Gitea）与自动构建，镜像合计约 845MB。只要核心：

Terminal window
curl -fsSL \
  https://code.ezboti.com/install.sh \
  | sh -s -- --no-gitea

不要自动构建时加 --no-runner。macOS 默认不含 Gitea；--with-gitea 在 macOS 上会报错。

参数

  • --deployment <代号>：部署代号，默认 default；数据目录、容器项目和卷名前缀都用它。
  • --public-url <url>：对外访问地址，默认自动探测。
  • --port <port>：服务端端口，默认 9630。
  • --version <buildId>：固定服务端版本并写入 .env；之后重跑沿用。
  • --latest：解除固定，更新到 latest。
  • --no-gitea：本次只要服务端、数据库和搜索服务，不起 Gitea。
  • --no-runner：起 Gitea，但不起自动构建。
  • --with-gitea：Linux 默认已含，不用传；macOS 上会报错。
  • -h、--help：查看当前脚本支持的参数。

--no-gitea / --no-runner 只对本次运行生效；升级时重跑同一条命令、带上原参数。

脚本默认用当前用户运行；只有装 Docker 时用 sudo。当前用户不在 docker 组时，脚本用 sudo docker 跑 compose；不自动 usermod，也不要求重新登录。macOS 一律不用 sudo。

装完做什么

  1. 浏览器打开命令输出的访问地址，用 8 位登录码创建第一个管理员。
  2. 网页「添加电脑」会给一行守护进程（daemon）命令（配置码 24 小时有效）；在那台电脑执行，等它上线。
  3. 用浏览器打开 <访问地址>/about 下载安卓客户端，填同一个地址登录。

服务端只负责管理，真正执行任务的是各台电脑；Mac mini 本身也要装一次守护进程。code.ezboti.com/install.sh 装服务端，<服务端地址>/install.sh 装守护进程，同名不同物。

自托管 Git（Gitea）

Linux 默认安装 Gitea 和自动构建服务。默认部署下：

  • 地址：http://<host>:13300
  • 管理员：admin
  • 初始口令：~/deploy/beecodeai-default/.env 里的 GITEA_ADMIN_PASSWORD

Linux 不需要 --with-gitea；macOS 默认不含 Gitea。只要服务端、不要 Git / 自动构建时，用 --no-gitea；要 Gitea、不要自动构建时用 --no-runner。

从含 Gitea 的部署切到 --no-gitea 前，先到服务端界面清除 Git 配置。服务端的配置优先级是数据库 > 环境变量；界面上保存过 Git 配置时，只置空 env 不会生效，服务端仍会指向已删除的 Gitea。

前提

  • Linux（Ubuntu 24.04）或 macOS（Apple Silicon）+ OrbStack；
  • 服务端数据目录所在分区剩余空间不少于 2 GiB（镜像合计约 845MB，建议留 4 GiB 以上）；
  • 端口 9630 空闲；默认含 Gitea 时 13300（Web）和 13322（SSH）也要空闲；
  • 客户端能访问服务端。守护进程需要能连出去访问服务端；不需要服务端回连守护进程。

备份

升级前至少备份数据库、附件和 .env：

Terminal window
docker exec -u postgres beecodeai-postgres-default pg_dumpall -U beecodeai > beecodeai-db.sql
docker cp beecodeai-server-default:/var/lib/beecodeai-server/attachments ./attachments
cp ~/deploy/beecodeai-default/.env ./beecodeai.env

.env 里有主密钥；丢了它，数据库里的密文无法解密。自定义 --deployment 时，把命令里的 default 换成你的代号。

升级与回滚

普通重跑按 .env 里的 BEECODEAI_SERVER_TAG 来：固定过版本就一直用那个版本；要更新到 latest 加 --latest，要切到或回滚到某个 buildId 加 --version <buildId>。

Terminal window
# 更新到 latest
curl -fsSL \
  https://code.ezboti.com/install.sh \
  | sh -s -- --latest


# 固定 / 回滚到某个 buildId
curl -fsSL \
  https://code.ezboti.com/install.sh \
  | sh -s -- --version <buildId>

重跑会重新生成 compose 模板、复用已有的 .env 与数据卷。升级前先备份；数据库 migration 是单向的。

验收

Terminal window
BASE=http://<地址>:9630
curl -sS -X POST -H 'content-type: application/json' \
  -d '{}' "$BASE/api/server/health"
curl -sS -o /dev/null \
  -w '%{http_code} %{content_type}\n' \
  "$BASE/dl/<buildId>/metadata.json"

两条都应返回 200。然后浏览器打开访问地址，用登录码创建管理员。

常见卡点

  • Docker 装不上：只支持 Ubuntu 自动装 Docker；其它发行版先自行安装 Docker Engine + Compose v2，或改用离线包。
  • macOS 检测不到 Docker：先安装并启动 OrbStack，再重跑命令。
  • macOS SSH 下拉镜像报 keychain 错误：OrbStack 在 SSH 会话里取不到登录钥匙串，不是脚本问题；在 Mac 图形终端重跑同一条命令。
  • 地址打不开：先打开命令打印的访问地址；如果还打印了 Tailscale 地址或局域网地址，换另一个试；确认 9630 已放行、客户端能访问这台电脑。
  • Gitea 打不开 / 克隆失败：确认 13300（Web）和 13322（SSH）已放行；管理员口令在 .env 的 GITEA_ADMIN_PASSWORD。
  • 端口占用：首次安装加 --port 9631；或释放 9630。
  • 镜像拉取慢：默认走腾讯云 TCR；确认能访问 ccr.ccs.tencentyun.com。
  • 首装失败：重跑同一条命令；数据目录脏了按报错提示清理。

离线 / 企业部署

不能出网、或需要企业离线包时，用 sudo ./deploy.sh，见离线包部署。企业版的服务范围见企业版。