15 KiB
在 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_AI_PROVIDER=openai
PCB_CODEX_AUTH=apikey
OPENAI_API_KEY=填入与该地址对应的服务端Key
PCB_OPENAI_BASE_URL=https://api.vip1129.cc
PCB_OPENAI_MODEL=gpt-6.1-sol
DEEPSEEK_API_KEY=
PCB_DEEPSEEK_MODEL=deepseek-flash
ARK_API_KEY=
PCB_DOUBAO_MODEL=doubao-seed-2-1-pro-260915
PCB_CODEX_IDLE_TIMEOUT=300
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_OPENAI_MODEL、PCB_DEEPSEEK_MODEL、PCB_DOUBAO_MODEL 必须分别是对应账号可用的准确模型 ID;服务不会自动替换模型。PCB_REASONING_EFFORT 也必须受所选模型支持,可用 PCB_<服务>_REASONING_EFFORT 分别覆盖。旧的 PCB_MODEL 只作用于默认服务,建议迁移为各服务独立设置。真实 Key 只放服务器的 .env.local,不要放进 .env.example、Dockerfile 或 VITE_*。
PCB_OPENAI_BASE_URL 是模型 API 的基础地址,与前端连接 PCB 后端的 PCB_API_TARGET 不同。当前项目的 OpenAI 兼容服务默认地址为 https://api.vip1129.cc;这是用户指定的兼容服务,不是 OpenAI 官方地址。若使用官方 OpenAI 账号,明确设为 https://api.openai.com/v1 并使用与该服务对应的 Key。如果凭据由兼容 Responses API 的其他服务签发,需明确配置该服务提供的基础地址,并使用与之匹配的 Key;是否带 /v1 以该服务说明为准,不要填写 /responses 完整接口地址。后端不会读取或继承个人 ~/.codex/config.toml 中的模型服务地址,也不会自动切换服务或模型。地址禁止包含用户名、密码、查询参数或片段;Key 仍通过环境变量或 secret 文件注入。
OpenAI / DeepSeek / 豆包切换
PCB_AI_PROVIDER 设定网站新建设计的默认服务,可选 openai(项目默认)、deepseek、doubao。用户可在新建设计表单的「AI 服务」中切换已配置的服务;缺少凭据的选项会禁用。选择在任务创建时保存,方案修改、生产和重启继续使用同一服务、模型及原生会话;已有设计不跨服务迁移,需要切换时新建设计。
| 服务 | 基础地址变量 / 默认值 | 模型变量 / 默认值 | 凭据变量 |
|---|---|---|---|
| OpenAI 兼容服务 | PCB_OPENAI_BASE_URL / https://api.vip1129.cc |
PCB_OPENAI_MODEL / gpt-6.1-sol |
OPENAI_API_KEY 或 OPENAI_API_KEY_FILE |
| DeepSeek | PCB_DEEPSEEK_BASE_URL / https://api.deepseek.com |
PCB_DEEPSEEK_MODEL / deepseek-flash |
DEEPSEEK_API_KEY 或 DEEPSEEK_API_KEY_FILE |
| 豆包(火山方舟) | PCB_DOUBAO_BASE_URL / https://ark.cn-beijing.volces.com/api/v3 |
PCB_DOUBAO_MODEL / doubao-seed-2-1-pro-260915 |
ARK_API_KEY 或 ARK_API_KEY_FILE;兼容 DOUBAO_API_KEY / DOUBAO_API_KEY_FILE |
三种服务都通过原生 Codex 的 Responses 协议运行,不引入旧版设计流水线。DeepSeek 使用官方 Responses 接口及原生模型元数据;豆包使用方舟 Responses 接口,需先在方舟控制台开通所选模型,亦可将模型设置为账号实际部署的 Endpoint ID。豆包当前未启用内置联网搜索,批准生产后代理仍可通过原生Shell访问厂商文档。不能仅凭成功的HTTP健康检查认定Key、额度或模型权限可用。
GET /api/providers 返回默认服务、各服务模型及凭据是否配置,不返回Key。POST /api/sessions 可发送 {"text":"设计要求…","provider":"deepseek"};不填provider使用服务端默认值,未知服务返回400,未配置凭据返回503。每个任务仅向对应Codex进程传递该服务的凭据,其他模型Key及Key文件路径会从子进程环境中剔除;EDA子进程不接收模型凭据。变更已保存任务的模型/服务/地址会阻止继续执行,Key轮换不改变审批哈希。
参考:DeepSeek Responses API、DeepSeek Codex接入、火山方舟 Responses API。
原生模型请求的重试错误现在会显示在网站运行记录中,终止错误会将任务标记为失败。若连续 PCB_CODEX_IDLE_TIMEOUT 秒(默认300秒)没有原生模型进展,也会明确失败并保留会话供重试;仅有HTTP心跳或重连错误不会延长此期限。正在执行的原生工具请求使用其自身的执行超时,不由这个模型空闲期限中断。/api/health 返回当前认证模式、provider及API基础地址供核对,不返回凭据;ok: true 仍只代表HTTP服务可用。
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 工程数据位置时,也要额外挂载相应数据。