README.md 2.9 KB

离线部署材料(内网/无网环境)

目标:在一台完全不能联网的海关电脑上,从零装起来。

需要在能联网的电脑上先准备好两样东西,然后一起拷到目标电脑:


1. Python 依赖 wheel

在能联网的、和目标机同架构同 Python 版本的电脑上:

cd tools-service
python -m pip download -r requirements.txt -d ../offline/wheels

(Windows 上把 python 换成实际解释器路径;如果目标机是 Python 3.12,就用 3.12 下载。)

拷过去之后,启动.bat 会自动发现 offline/wheels/ 并执行:

python -m pip install --no-index --find-links offline/wheels -r requirements.txt

如果目标机连 pip 都没有(极简 Python),可以改用打包好的便携 Python: 把整个 python-3.12-embed-amd64 目录放到 offline/python/,然后在 .env 里设置

CDA_PYTHON=C:\path\to\offline\python\python.exe

2. Node 依赖(可选)

默认不需要:bff/dist(已编译的 BFF)与 web/dist(已构建的前端)都在仓库里, 目标机只要有 Node 就能直接运行,无需 npm install。

只有在你修改了 bff/src 或 web/src 需要重新构建时才需要 Node 依赖。做法:

在能联网的电脑上:

cd bff && npm install --no-audit --no-fund
cd ../web && npm install --no-audit --no-fund

然后把 bff/node_modules、web/node_modules 一起拷过去(体积较大,但一次性)。 或者使用离线 npm 缓存:

npm install --cache ./offline/npm-cache --prefer-offline

3. 目标机安装顺序

  1. 安装 Node.js(用官方 MSI,全离线安装包);
  2. 安装 Python(勾选 Add to PATH);
  3. 把整个项目文件夹(含 offline/wheels/、data/、.env)拷到目标机;
  4. 双击 启动.bat。

启动.bat 会依次:检查 Node/Python → 用 offline/wheels 装 Python 依赖 → 检查 bff/dist、web/dist 是否已构建(已有就跳过)→ 起两个服务 → 开浏览器。

如果构建产物缺失又无法联网,会明确提示:

✗ 缺少 bff/dist,且指定了 --skip-install。请先执行 npm install && npm run build。

此时需要在能联网的机器上构建好,把 bff/dist、web/dist 拷过来。


4. 目录清单

offline/
├─ README.md          # 本文件
├─ wheels/            # pip download 产出的 .whl(.gitignore 已排除,需自己生成)
├─ npm-cache/         # 可选:npm 离线缓存
└─ python/            # 可选:便携 Python 运行时

5. 校验

离线机上跑一次:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run_tests.ps1 -SkipE2E
node scripts/e2e.mjs --no-chat

前者验证引擎与接口,后者验证"上传→处理→读取→下载"全链路(不需要联网、不需要模型 Key)。