跳转到内容
PicoAide Wiki

部署总览

PicoAide Harness 面向企业内网交付：一台服务器跑服务端，员工装客户端，数据与密钥都在企业自己的机器上。 本页说明部署形态与交付物；具体操作见本节其余页面。

仓库内的 docs/deploy/AI-DEPLOY.md 是唯一权威的部署说明（首次部署 / 升级 / 回滚 / 排障 + 四条数据安全铁律），可以直接交给 AI 代理执行。 本 Wiki 是面向人的同一套流程，两者出现偏差时以仓库文档与代码为准。

三种部署形态

Section titled “三种部署形态”
形态适用说明入口
单机桌面个人 / 小团队只装桌面客户端。客户端自带本地 Harness 运行时并在本机启动服务，会话与凭据留在本机，无需服务器桌面客户端
企业内网容器化（推荐）组织全员内网服务器跑 caddy + server + postgres 三个容器；账号、网关、配额、计费、审批集中在服务端容器化部署
并入已有反代 / 单二进制已有统一入口的机房80/443 已被共享 Caddy/nginx 占用时只起 server + postgres 并入现有 vhost；也支持单二进制 + 外部 PostgreSQL（含从 systemd 迁移）运维与排障

交付物：一个镜像 + 一份说明

Section titled “交付物：一个镜像 + 一份说明”

服务端只有一种发布物：一个容器镜像。镜像里已经装好部署需要的一切，不需要克隆仓库、不需要外网拉配置、 也没有任何安装脚本。

发布物 = 一个容器镜像
  ├─ 服务端二进制（含内嵌 webadmin 管理后台）
  ├─ 三平台客户端安装包 + CLIENT-RELEASE.json   ← 员工从这里下载
  ├─ docker-compose.yml + Caddyfile.{internal,autocert,manual} + .env.example
  ├─ VERSION / CHANNEL                          ← 本部署的版本与渠道
  └─ channel/                                   ← 品牌与文案（渠道内容）

一条命令即可把部署文件导出到部署目录（镜像自带的 PICOAI_UNPACK_STACK 入口）：

Terminal window
mkdir -p /opt/picoaide
docker run --rm -v /opt/picoaide:/out -e PICOAI_UNPACK_STACK=/out \
  picoaide-harness-server:<版本>
ls -1 /opt/picoaide   # docker-compose.yml / Caddyfile.* / .env.example / VERSION / client/

导出是替换语义：docker-compose.yml、Caddyfile.*、.env.example、client/、VERSION 会先清旧再写； .env、picoaide-data/、pg-data/、caddy-data/、certs/ 一律不动。

从哪里取镜像

Section titled “从哪里取镜像”

不经任何镜像仓库（GHCR 已下线）。所有渠道的镜像都从更新服务器取，每个渠道一个独立目录：

https://release.picoaide.com/<渠道>/latest.json                         ← 版本清单（服务端升级检查也读它）
https://release.picoaide.com/<渠道>/releases/<版本>/picoaide-server-<版本>-amd64.zip
https://release.picoaide.com/<渠道>/releases/<版本>/SHA256SUMS          ← 下载后务必校验

latest.json 的关键字段：

字段含义
channel_id该清单属于哪个渠道（服务端会强制比对，见渠道与白标）
server.version目标版本（不带 v，如 <版本>）
server.image_tag镜像 tag（带 v，如 v<版本>）；导入后 <版本> 与 v<版本> 两个 tag 都在，另有一个渠道专属 tag <channel-id>-<版本>（同机多栈必须用它，见升级、备份与回滚）
server.image_asset镜像压缩包下载地址
client.version随该版本镜像发布的客户端版本（与服务端同源）
  • 更新服务器只保留最近 3 个版本；更早的版本从 GitHub Release 取（公开渠道的完整历史存档）；
  • GitHub Release 只发公开渠道（官方 / 预发布）的镜像包与 SHA256SUMS；品牌渠道是客户定制交付，不经公开 Release；
  • 无外网环境见离线部署。

环境要求

Section titled “环境要求”
项目要求
服务器Linux x64；Docker ≥ 24 与 Compose v2（docker compose，不是 docker-compose）、openssl、curl、unzip
资源建议 ≥ 4 核 / 8GB 内存 / 50GB 可用磁盘（pg-data/ 会持续增长）
网络服务器需要能访问 https://release.picoaide.com（检查更新 + 下载镜像）；员工电脑不需要访问任何外网
端口Caddy 占用宿主机 80/443（可改 CADDY_HTTP_PORT / CADDY_HTTPS_PORT）
客户端Windows 10+ x64 / macOS 12+（Apple 芯片）/ Linux x64；无需 Node.js、pnpm 或 DSH

容器架构

Section titled “容器架构”
员工客户端 / 浏览器
      │ HTTPS(80/443)
      ▼
   Caddy 2（反代 + TLS 终结，固定 IP 172.28.0.2）
      │ HTTP:8080（仅 compose 私有网段）
      ▼
   Go 服务端（非 root uid 10001，固定 IP 172.28.0.3）
      │
      ▼
   PostgreSQL 18（内置容器，固定 IP 172.28.0.4，数据 ./pg-data）
  • 自定义 bridge 私有网段（默认 172.28.0.0/24，NETWORK_SUBNET 可改），容器 IP 固定在 compose 里声明， 重建/升级后不变；
  • server 不映射宿主机端口，外部流量只能经 Caddy 进入（内网隔离 + 攻击面收敛）；
  • 全部持久化数据用 ./ bind mount，不使用命名卷：
目录内容备注
picoaide-data/应用数据 + master.key丢失 = 数据库内加密的上游密钥永久不可解，必须备份
pg-data/内置 PostgreSQL 18 数据挂载到容器 /var/lib/postgresql（PG18 起数据落 18/docker/ 子目录）
caddy-data/ caddy-config/Caddy 证书库与配置auto 模式必须备份，否则重新签发
certs/手动证书仅 manual 模式
deploy-backup/备份输出备份步骤写入

应用访问模型（2026-09-19 起：应用不需要公网入口）

Section titled “应用访问模型（2026-09-19 起：应用不需要公网入口）”

员工自建的 WASM 应用只在桌面客户端内打开：客户端为应用开一个独立窗口，加载自定义协议地址 <渠道 app 源 scheme>://<app_id>/（scheme 由渠道配置决定，官方渠道为 picoaide-app）， 由客户端转发到服务端唯一入口 POST /api/client/v2/apps/wasm/:app_id/request（携带员工令牌）执行。

  • 服务器不需要为应用准备任何公网访问面：不需要应用专用域名解析、不需要应用专用证书、 Caddy 也不需要额外的站点块 —— 下节的三种证书模式都只服务主站域名；
  • 2026-09-19 之前的”应用独立域名 + 浏览器访问”链路已整体删除，浏览器不再能访问应用；
  • 升级必须服务端与客户端同版本：旧客户端无法再打开应用，需把员工客户端一起升到配套版本 （客户端随服务端镜像分发，见客户端分发与升级）。

证书模式（三选一）

Section titled “证书模式（三选一）”

由 .env 的 TLS_MODE 决定挂载哪个 Caddyfile 模板：

模式模板适用前提
internalCaddyfile.internal纯内网 / 无公网域名（最常见）无；客户端首次连接需信任 Caddy 本地 CA
autoCaddyfile.autocert有公网域名且直连本机域名 A 记录指向本机公网 IP、80/443 对公网开放；经 CDN 会失败，不接受 IP
manualCaddyfile.manual企业已有正式证书（支持 IP）提供 certs/server.crt + certs/server.key

判断方法：域名解析到公网且能直连 → auto；否则 → internal。IP 部署一律 internal 或 manual。

四条铁律（违反会造成不可恢复的数据损失）

Section titled “四条铁律（违反会造成不可恢复的数据损失）”
#禁止原因
1绝不执行 docker compose down -v、docker volume prune、docker system prune --volumes-v / prune 会删数据卷与镜像层，数据库和 master.key 一起没；数据在 bind mount 目录里，down（不带 -v）不会删
2绝不用 latest 标签不可复现、无法回滚锚定；一律用 vX.Y.Z 具体版本
3升级前必须备份，且确认备份文件非空picoaide-data（含 master.key）+ pg_dump；master.key 丢了，库里所有加密的上游密钥永久无法解密
4不得用 .env 覆盖已有部署目录部署目录已有 .env 说明部署过，那是升级场景，走升级流程而不是重装

补充：不要在健康检查通过前删旧镜像（它是回滚锚点）；不要为让服务起来而改 compose 里的固定 IP / 网段； 数据库迁移不可逆，回滚镜像不能把数据库降回旧结构。

接下来

Section titled “接下来”
  1. 容器化部署 —— 从取镜像到健康检查的完整首次部署
  2. 升级、备份与回滚 —— 版本检查、备份、切换与回退
  3. 客户端分发与升级 —— 客户端随服务端发布，员工零外网
  4. 渠道与白标 —— 官方 / 预发布 / 企业定制渠道
  5. 离线部署 —— 服务器不能出网时的旁路取包
  6. 运维与排障 —— 反代、证书、备份恢复、常见故障