Files
vibemake-pcb-studio/codex_pcb/DEPLOY.md
T
admin e7f19ff493
CI / typecheck + test + build (push) Has been cancelled
部署更改
2026-11-13 17:20:03 +08:00

11 KiB
Raw Blame History

在 1Panel 部署 PCB AI 后端

后端可独立于前端部署。仅上传 codex_pcb/ 会缺少独立 EDA API 文档;推荐使用下述部署包,不需要上传整个仓库或运行旧版 backend/ 服务。

1. 在本地生成上传包

在仓库根目录执行:

python3 scripts/package-pcb-backend.py

如果服务器访问 GitHub 慢,在本地网络可访问 GitHub 时改用:

python3 scripts/package-pcb-backend.py --with-freerouting

该选项将固定版本的 Freerouting JAR 和许可一起放入部署包,并核对 JAR 的 SHA-256。下载缓存在本地 dist/pcb-backend-downloads/,重复打包不再下载;程序会优先使用系统 curl 的正常证书验证。服务器构建时直接使用包内文件,无需下载这两个 GitHub 文件。

生成 dist/vibemake-pcb-backend.tar.gz,包含当前后端源码、Dockerfile、Compose、启动脚本、Python 依赖、独立 API 参考文档和许可说明。打包按明确的文件清单进行,不包含 .env.local、任务历史、个人登录文件、前端、旧设计流程或嘉立创程序。

上传压缩包到 Linux 服务器,在 1Panel 文件管理器中解压到 /opt,结果应为:

/opt/vibemake-pcb-backend/
├── LICENSE
├── codex_pcb/
│   ├── Dockerfile
│   ├── Dockerfile.dockerignore
│   ├── compose.yaml
│   ├── docker-entrypoint.sh
│   ├── requirements.txt
│   ├── .env.example
│   └── ...Python 后端源码
├── backend/easyeda_backend/skills/easyeda-api/
│   ├── SKILL.md
│   └── references/
└── vendor/lceda-pro/                 # 需自行放入完整的 Linux EDA 程序

其中 backend/ 只包含官方 API 文档和来源元数据,容器不启动旧版服务。

2. 准备嘉立创 EDA 专业版 Linux 程序

从官网下载页获取与服务器 CPU 架构一致的专业版 Linux ZIP。服务器 uname -m 的 x86_64 对应 x64,aarch64 对应 arm64。不要上传 macOS/Windows 程序。CLI 要求支持 open、session list、invoke --code-file 的专业版客户端,运行前请核对其 --help。

按压缩包内说明解压,找到实际包含 lceda-pro 可执行文件的完整应用目录,将该目录的内容放入:

/opt/vibemake-pcb-backend/vendor/lceda-pro/

确保 vendor/lceda-pro/lceda-pro 是可执行程序;保留应用全部资源、共享库、辅助程序及符号链接,不要只复制一个二进制文件。若外层还有一层目录,需要展开到上述位置。程序以只读方式挂载到容器 /opt/lceda-pro,不打进镜像。

cd /opt/vibemake-pcb-backend
chmod +x vendor/lceda-pro/lceda-pro

如果发行包采用其他入口名称,修改 .env.local 的 PCB_EDA_BIN 为挂载目录中实际路径。首次激活、账号登录、组件库访问以及该版本在虚拟显示上的运行仍需在目标服务器验证;OpenAI Key 不代替嘉立创客户端所需的配置。

3. 填写后端环境变量

cp codex_pcb/.env.example codex_pcb/.env.local
chmod 600 codex_pcb/.env.local

在 1Panel 文件编辑器中填写:

PCB_CODEX_AUTH=apikey
OPENAI_API_KEY=填入新生成的服务端Key
PCB_SESSION_ROOT=/data
PCB_CODEX_HOME=/data/codex-home
PCB_CODEX_BIN=/usr/local/bin/codex
PCB_EDA_BIN=/opt/lceda-pro/lceda-pro
PCB_BLENDER_BIN=/usr/bin/blender
PCB_FREEROUTING_JAR=/opt/pcb-resources/freerouting.jar
DISPLAY=:99
XDG_RUNTIME_DIR=/tmp/pcb-xdg

PCB_MODEL 必须是 OpenAI API 项目有权限使用的准确模型 ID;示例保留现有的 gpt-6.1-sol,这不代表每个 API 项目均可访问。PCB_REASONING_EFFORT 也必须受所选模型支持。真实 Key 只放服务器的 .env.local,不要放进 .env.example、Dockerfile 或 VITE_*。

Compose 的 env_file 会将 .env.local 注入后端。Dockerfile 的专用 ignore 文件只允许后端源码和 API 文档进入构建上下文,排除密钥、程序包及运行数据。不要使用 docker compose config 的完整输出对外分享配置,其中可能包含已展开的环境变量。

4. 构建并启动

在服务器终端执行:

cd /opt/vibemake-pcb-backend
docker compose -f codex_pcb/compose.yaml up -d --build
docker compose -f codex_pcb/compose.yaml logs --tail=100 -f pcb-backend

或者在 1Panel「容器 → 编排 → 创建编排 → 路径选择」选择:

/opt/vibemake-pcb-backend/codex_pcb/compose.yaml

需要预先在「容器 → 镜像」构建时,Dockerfile 选择 codex_pcb/Dockerfile,构建上下文必须是 /opt/vibemake-pcb-backend,不是其 codex_pcb/ 子目录;镜像名用 vibemake-pcb-backend:local。

镜像使用 Node 22 / Debian Bookworm,安装 Python、Codex CLI(固定版本)、Java 17、Blender、Xvfb/xauth、字体及常用 Electron 库,并下载或读取包内的 Freerouting 1.9.0,始终校验其 SHA-256。构建需要服务器能访问基础镜像仓库及所选软件源;未预装路由器资源时,还需要访问 GitHub。入口先检查依赖和凭据是否存在,再启动虚拟显示及一个 Uvicorn worker。它不会自动检查 Key 额度或模型权限,也不会自动完成客户端激活。

可用以下命令独立构建:

docker build -f codex_pcb/Dockerfile -t vibemake-pcb-backend:local .

国内下载源与缓存

Dockerfile 和 Compose 默认使用以下国内源,可在 codex_pcb/compose.yaml 的 build.args 中修改:

参数 默认值 下载内容
DEBIAN_MIRROR http://mirrors.tuna.tsinghua.edu.cn/debian Python、Blender、Java、图形运行库
DEBIAN_SECURITY_MIRROR http://mirrors.tuna.tsinghua.edu.cn/debian-security Debian 安全更新
NPM_REGISTRY https://registry.npmmirror.com Codex CLI 及匹配平台的原生包
PIP_INDEX_URL https://mirrors.ustc.edu.cn/pypi/simple FastAPI、Uvicorn 及 Python 依赖

Debian 12 的 DEB822 .sources 文件及传统 .list 都会换源;仍使用 Debian 自带的包签名校验。APT 默认使用 HTTP 以支持尚未安装 CA 证书的 slim 基础镜像,npm/pip 保持 HTTPS 验证。不要通过关闭验证或添加 trusted-host 处理网络问题。

这些是构建参数,放在后端运行时 .env.local 中不会自动作用于镜像构建。修改 Compose 的 build.args,或直接构建时传 --build-arg。例如回到官方源:

docker build -f codex_pcb/Dockerfile -t vibemake-pcb-backend:local \
  --build-arg DEBIAN_MIRROR=http://deb.debian.org/debian \
  --build-arg DEBIAN_SECURITY_MIRROR=http://deb.debian.org/debian-security \
  --build-arg NPM_REGISTRY=https://registry.npmjs.org \
  --build-arg PIP_INDEX_URL=https://pypi.org/simple .

某个固定版本尚未同步到镜像站时,可单独切换对应源,无需更改版本。BASE_IMAGE 可指定你自己可信仓库中的 Node 22 Bookworm slim 镜像;FREEROUTING_URL 和 FREEROUTING_LICENSE_URL 可指向自己维护的下载地址,JAR 校验保持不变。

基础镜像 node:22-bookworm-slim 在执行 Dockerfile 的 RUN 之前拉取,不受上述 apt/npm/pip 源控制。若这一步慢,在 1Panel「容器 → 配置 → 镜像加速」中配置镜像加速器;1Panel 官方文档当前列出 https://docker.1panel.live。已成功拉取的基础镜像会复用本地缓存。

镜像构建使用 BuildKit 缓存 APT、npm 和 pip 下载,并将三类安装拆成独立步骤;npm 或 Python 安装失败时不必重新安装已经完成的系统依赖。换源仅对下一次构建生效,已经运行的构建不会自动切换下载地址。更新部署文件后重新执行 docker compose -f codex_pcb/compose.yaml up -d --build 即可,不要加 --no-cache。

来源:清华 Debian 镜像说明、中科大 PyPI 镜像说明、npmmirror 使用说明。

5. 验收并接上现有网站

先检查服务器本机接口:

curl -f http://127.0.0.1:8003/api/health
docker compose -f codex_pcb/compose.yaml exec pcb-backend codex --version
docker compose -f codex_pcb/compose.yaml exec pcb-backend codex sandbox -- /bin/true
docker compose -f codex_pcb/compose.yaml exec pcb-backend /opt/lceda-pro/lceda-pro --help --no-sandbox
docker compose -f codex_pcb/compose.yaml exec pcb-backend /opt/lceda-pro/lceda-pro session list --no-sandbox

codex sandbox -- /bin/true 不调用模型,用于检查目标 Linux/Docker 是否允许 Codex 创建本机沙箱。若出现 namespace、bubblewrap、Landlock 或 seccomp 错误,需要先核对宿主机内核与容器策略;这与 Key 无关。此模板保留原生沙箱,没有添加 privileged 或自动关闭 Codex 沙箱。该项必须在目标服务器验收,当前本机的配置解析不能替代它。

如果使用 scripts/serve.mjs,同机前端服务设置 PCB_API_TARGET=http://127.0.0.1:8003。若前端也在 Docker 的桥接网络中,改为同网络下的 http://pcb-backend:8003。

1Panel OpenResty 使用宿主机网络时,网站增加以下规则;若已有同路径代理,请更新原规则,避免重复:

location ^~ /pcb/pcb-api/ {
    proxy_pass http://127.0.0.1:8003/api/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_buffering off;
    proxy_read_timeout 3600s;
}

OpenResty 若使用桥接网络,其 127.0.0.1 指向 OpenResty 自身。此时把 PCB 和 OpenResty 加入同一个 Docker 网络,用 http://pcb-backend:8003/api/ 转发。例如确认 OpenResty 已在 1panel-network 后,在 Compose 最外层添加:

networks:
  default:
    external: true
    name: 1panel-network

网络名以面板实际配置为准。改动后重建容器;无需将 8003 公开到互联网。当前 API 为共享任务服务,对外开放网站前仍需服务端认证和任务归属校验。

最后通过网站新建方案、审核启动,验证完整的绘板及交付下载。HTTP 健康并不等于原生绘板成功。

数据、备份与升级

pcb-data 命名卷挂载到 /data,包含任务、交付、Codex 会话和以 /data/home 为 HOME 的 EDA 用户数据。默认 Compose 项目名为 vibemake-pcb,卷名通常为 vibemake-pcb_pcb-data。不要执行 docker compose down -v;该操作会删除数据卷。改用宿主机 bind mount 时,目录需允许 UID/GID 10001:10001 写入。

更新代码后重新生成上传包,替换源码、文档及部署文件,保留服务器的 .env.local、vendor/ 和命名卷,然后重新执行 up -d --build。有已批准任务时先完成该任务再升级;旧任务的源码冻结校验不能通过修改哈希绕过。

新增空卷时入口会将 /data/resources 链接到镜像中的 /opt/pcb-resources,文档随镜像升级;如果迁移现有运行目录,则保留原有 resources/ 并检查其文档和路由器路径。独立更改 PCB_CODEX_HOME 或 EDA 工程数据位置时,也要额外挂载相应数据。

参考:1Panel 编排、Docker 构建上下文、嘉立创 CLI。