必须使用预下载离线包完成构建与运行：先在有网环境执行scripts/fetch-offline-deps.sh拉取全部依赖并归档至offline-bundle/，再传入离线服务器校验完整性，最后通过本地Node.js/Python路径和--offline/--no-index等参数免联网构建启动。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在没有外网连接的生产服务器、政企内网或涉密隔离环境中，需要完整部署腾讯云开源 AI 助手 Octop，必须绕过 npm install、pip install、git clone 等依赖远程源的操作，全部使用预下载的离线包完成构建与运行。
准备离线构建环境
在有网机器上，用 Ubuntu 22.04 或 CentOS 7.9 系统执行以下操作：下载 Octop 主仓库及全部子模块（含 frontend、backend、core）→ 运行 scripts/fetch-offline-deps.sh 脚本（该脚本已内置在 Octop v0.3.0+ 源码中）→ 自动拉取 Node.js 18.18.2 二进制包、Python 3.11.9 嵌入式压缩包、yarn 1.22.19 离线 tarball、所有 npm 包 tgz 文件、所有 PyPI wheel 文件，并按依赖树结构归档到 offline-bundle/ 目录。
这一步不能跳过，【若漏掉 scripts/fetch-offline-deps.sh 中任一子步骤，后续 build 将因缺失 @octop/core 或 pydantic-core.whl 报错中断】。脚本执行耗时约 12 分钟，输出日志末尾必须出现 “✅ All offline assets collected” 才算成功。
将整个 offline-bundle/ 目录连同 octop/ 源码根目录一起打包为 octop-offline-v0.3.0.tar.gz，通过 U 盘或内网 FTP 传入目标离线服务器。
解压并校验离线包完整性
在离线服务器上执行： tar -xzf octop-offline-v0.3.0.tar.gz → 进入 octop/ 目录 → 运行 ./scripts/verify-offline-integrity.sh 。
该脚本会逐项比对 SHA256 列表（已预置在 offline-bundle/SUMS 中），检查 Node.js 二进制、Python wheel、frontend/node_modules 内每个 tgz 解压后实际内容是否与预期一致。任何一项校验失败，脚本立即退出并提示具体缺失文件路径。
注意：此校验不检查网络连通性，只验证本地文件有效性。若提示 pydantic-core-2.16.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl mismatch，说明该 wheel 在传输过程中损坏，需重新拷贝。
使用 Model Studio DashScope SDK，调用通义万象图像生成模型（qwen-image、qwen-image-plus、qwen-image-max 及快照版）生成图像。适用于实现图像生成功能。
免联网构建前端与后端
方法一：全本地 yarn 构建（推荐）
执行 export NODE_ENV=production && export PATH=$(pwd)/offline-bundle/node-v18.18.2-linux-x64/bin:$PATH → 运行 yarn --offline --no-lockfile install → 等待终端输出 “Done in 42.34s” → 执行 yarn build:prod 。
方法二：跳过前端构建，直接复用预编译产物
若离线包中已包含 offline-bundle/dist/ 目录，可直接 cp -r offline-bundle/dist ./backend/static，省去 8 分钟构建时间。但【此方式要求 backend 版本与 dist 内 build manifest.json 中的 commit hash 完全一致，否则启动时报 404】。
方法三：Python 后端纯离线安装
执行 export PYTHONHOME=$(pwd)/offline-bundle/python-3.11.9-embed-amd64 → export PATH=$PYTHONHOME:$PATH → ./offline-bundle/python-3.11.9-embed-amd64/python.exe -m pip install --find-links offline-bundle/wheels --no-index --only-binary=all octop-backend 。
启动 Octop 服务
第一步：初始化配置
运行 ./backend/octop-cli init --offline --data-dir /opt/octop-data 。该命令不联网，仅生成 /opt/octop-data/config.yaml 和空 memory.db 。
第二步：加载离线模型适配器
将预下载的 Qwen2-1.5B-Instruct-GGUF（量化版）放入
/opt/octop-data/models/
，并在 config.yaml 中设置：
llm: {type: llama, path: "/opt/octop-data/models/Qwen2-1.5B-Instruct.Q4_K_M.gguf"}
。第三步：启动服务
执行 ./backend/octop-cli serve --host 0.0.0.0:8080 --no-browser 。终端输出 “Octop server listening on http://0.0.0.0:8080” 即表示启动成功。
