chore: move offline release assets to standalone repository

2026-08-27 23:35:57 +08:00
1 parent 973500a0f0
commit 3715af3138
@@ -1,218 +0,0 @@
-# DeerFlow 纯离线标准发版与部署
-
-本文定义本仓库后续唯一的 Linux AMD64 离线发版方式。每次发版都必须从最新
-`master` 构建，使用
-`deploy/linux-docker-offline-deerflow-only/build-release.sh`，最终包只包含
-DeerFlow 后端和前端两张镜像，不包含 WeKnora 服务或镜像。
-
-## 1. 标准能力基线
-
-标准离线包必须同时具备以下能力：
-
- `config/deploy.env` 是唯一需要人工修改的配置源；生成文件不得手工修改。
- MySQL 使用 SQLAlchemy 异步 URL `mysql+aiomysql://`。
- 基础兼容版本为 `aiomysql 0.3.2`、`PyMySQL 1.2.0`、
-  `SQLAlchemy 2.0.51`。
- `deploy.env` 支持 1～20 个模型；编号为 1 的模型是默认模型。
- `source/wheelhouse` 支持完全离线增加 Python 依赖，安装结果保存在 Docker
-  named volume 中。
- 后端镜像内置 DOC/DOCX、XLS/XLSX、PPT/PPTX、PDF 处理能力，以及
-  LibreOffice、Pandoc 和中文字体。
- `OFFLINE_INSTALL.sh --stop` 只停止容器，不删除已加载镜像、数据目录或
-  named volume。
- `OFFLINE_INSTALL.sh --restart` 不重新 load 镜像；它重新渲染配置、检测
-  wheelhouse、校验源码并重建容器，使覆盖后的前后端源码生效。
- 启动脚本兼容 `docker-compose` 和 `docker compose`。
-
-## 2. 仓库中的标准目录
-
-| 路径 | 用途 |
-|---|---|
-| `deploy/linux-docker-offline-deerflow-only/` | 标准构建脚本、运行模板、测试和交付文档 |
-| `deploy/linux-docker-offline/Dockerfile.backend` | 后端基础镜像构建文件 |
-| `deploy/linux-docker-offline/Dockerfile.frontend` | 前端基础镜像构建文件 |
-| `deploy/linux-docker-offline/sanitize_release_sources.py` | 发布源码清理器 |
-| `offline-backend-20260512/wheelhouse/` | 随包携带的 Linux AMD64 / Python 3.12 基础 wheel |
-| `offline-backend-20260512/backend/` | 后端源码 |
-| `frontend-web/` | 前端源码 |
-
-不要使用历史的 DeerFlow + WeKnora 全量部署模板发本项目的标准包。
-
-## 3. 每次发版前更新源码
-
-发版工作区必须没有未提交的业务源码修改。未跟踪的本地构建产物不得混入包中。
-
-```bash
-git switch master
-git fetch origin master
-git merge --ff-only origin/master
-git status --short --branch
-git log -1 --format='%H %ad %s' --date=iso-strict
-```
-
-必须记录最终提交的完整 SHA。构建服务器如果使用不带 `.git` 的源码快照，应通过
-`DEERFLOW_COMMIT_OVERRIDE` 写入同一个 SHA。
-
-## 4. wheelhouse 维护
-
-基础 wheel 位于 `offline-backend-20260512/wheelhouse/`。最终包构建时会把它们
-复制到 `source/wheelhouse/`，并保留运行模板中的 `requirements.txt` 和说明文件。
-
-增加依赖时：
-
-1. 下载与 Linux AMD64、Python 3.12 匹配的 wheel，以及它的全部传递依赖。
-2. 把 wheel 放入 `offline-backend-20260512/wheelhouse/`。
-3. 在
-   `deploy/linux-docker-offline-deerflow-only/release-template/source/wheelhouse/requirements.txt`
-   中加入精确版本，例如 `some-package==1.2.3`。
-4. 重新生成并核对 `offline-backend-20260512/wheelhouse/SHA256SUMS`。
-5. 运行发布渲染测试，再构建完整包。
-
-不能放源码包、Windows wheel、macOS wheel，不能只放顶层依赖而遗漏传递依赖。
-
-部署完成后临时增加依赖时，也可以直接把 wheel 放进已解压交付目录的
-`source/wheelhouse/`，更新其中的 `requirements.txt`，然后执行：
-
-```bash
-./OFFLINE_INSTALL.sh --restart
-```
-
-安装器按 `requirements.txt + wheel 文件` 的哈希判断是否需要重新安装，全程使用
-`--no-index`，不会访问互联网。
-
-## 5. 构建标准完整包
-
-推荐在联网的 Linux AMD64 Docker 构建服务器执行。以下示例把构建工作区和输出
-放在 `/opt/codex-build`，不会修改现网部署目录：
-
-```bash
-RELEASE_STAMP="$(date +%Y%m%d-%H%M%S)"
-COMMIT_SHA="$(git rev-parse HEAD)"
-SHORT_SHA="$(git rev-parse --short=8 HEAD)"
-BUILD_ROOT="/opt/codex-build/deerflow-full-${RELEASE_STAMP}-${SHORT_SHA}"
-
-RELEASE_STAMP="$RELEASE_STAMP" \
-DEERFLOW_COMMIT_OVERRIDE="$COMMIT_SHA" \
-DEERFLOW_DIRTY_OVERRIDE=false \
-bash deploy/linux-docker-offline-deerflow-only/build-release.sh \
-  "$(pwd)" "$BUILD_ROOT"
-```
-
-不要设置 `DEERFLOW_FRONTEND_RUNTIME_BASE` 来复用旧前端镜像，除非本次只修改
-`runtime-config.js`。从新 `master` 正式发版时必须从当前前端源码完整构建。
-
-输出文件为：
-
-```text
-${BUILD_ROOT}/dist/deerflow-linux-amd64-offline-${RELEASE_STAMP}.tar.gz
-${BUILD_ROOT}/dist/deerflow-linux-amd64-offline-${RELEASE_STAMP}.tar.gz.sha256
-```
-
-## 6. 发版前强制校验
-
-```bash
-python3 -m py_compile \
-  deploy/linux-docker-offline-deerflow-only/release-template/scripts/render_runtime.py \
-  deploy/linux-docker-offline-deerflow-only/release-template/scripts/preflight_mysql.py \
-  deploy/linux-docker-offline-deerflow-only/release-template/scripts/install_wheelhouse.py
-
-python3 deploy/linux-docker-offline-deerflow-only/test_release_renderer.py "$(pwd)"
-bash -n deploy/linux-docker-offline-deerflow-only/build-release.sh
-
-cd "${BUILD_ROOT}/dist"
-sha256sum -c "deerflow-linux-amd64-offline-${RELEASE_STAMP}.tar.gz.sha256"
-gzip -t "deerflow-linux-amd64-offline-${RELEASE_STAMP}.tar.gz"
-```
-
-还必须确认：
-
- `images/deerflow-image-list.txt` 恰好只有 DeerFlow 后端、前端两行。
- `VERSION.json` 的提交 SHA 与本次 `master` 一致。
- 包含 `source/wheelhouse`、`scripts/install_wheelhouse.py` 和第 13 章文档。
- 后端镜像能导入 `aiomysql`、`PyMySQL`、`SQLAlchemy`。
- 后端镜像 Office 自检输出 `OFFICE_RUNTIME_SELF_CHECK=PASS`。
- 配置渲染后数据库驱动为 `mysql+aiomysql`。
-
-## 7. 新机器完全离线部署
-
-把 `.tar.gz` 和 `.sha256` 一起复制到目标服务器后执行：
-
-```bash
-sha256sum -c deerflow-linux-amd64-offline-*.tar.gz.sha256
-tar -xzf deerflow-linux-amd64-offline-*.tar.gz
-cd deerflow-linux-amd64-offline-*
-cp config/deploy.env.example config/deploy.env
-vi config/deploy.env
-./OFFLINE_INSTALL.sh --start
-```
-
-至少修改：
-
- `PUBLIC_HOST`、前后端端口；
- MySQL 地址、端口、数据库名、用户名、密码；
- `DEERFLOW_MODEL_COUNT`；
- 每个 `DEERFLOW_MODEL_N_*` 模型块；
- 实际需要启用的搜索、认证和外部业务接口配置。
-
-禁止直接修改 `data/generated/compose.env`、生成后的 `config.yaml` 或前端
-`runtime-config.js`；它们会在下次启动或重启时被 `deploy.env` 重新生成。
-
-常用命令：
-
-```bash
-./OFFLINE_INSTALL.sh --start
-./OFFLINE_INSTALL.sh --restart
-./OFFLINE_INSTALL.sh --stop
-./OFFLINE_INSTALL.sh --status
-```
-
-## 8. 只替换源码的更新方式
-
-后端可以覆盖交付目录中的：
-
-```text
-source/backend/app/
-source/backend/packages/
-source/backend/tests/
-```
-
-前端先在构建机执行 `pnpm build`，再覆盖：
-
-```text
-source/frontend/dist/
-```
-
-覆盖完成后只执行：
-
-```bash
-./OFFLINE_INSTALL.sh --restart
-```
-
-如果 Python 依赖或系统依赖发生变化，不能只替换源码：Python wheel 应同步更新
-`source/wheelhouse`；LibreOffice、Pandoc、字体或系统库变化必须重新构建后端镜像并
-发布新的完整包。
-
-## 9. 数据、停止与回退
-
- `--stop` 不删除镜像、数据或依赖 volume。
- 业务数据和生成配置保存在交付目录的 `data/`，升级前必须整体备份。
- 新版本应解压到新的版本目录，不要直接覆盖旧版本目录。
- 回退时停止新目录，在旧目录执行 `./OFFLINE_INSTALL.sh --start`。
- 不执行 `docker compose down -v`，除非明确要销毁数据并已经完成备份。
-
-服务器交付目录建议统一使用 `/opt/deerflow-offline-delivery/`；至少保留当前版本和
-上一个已验证版本，并保留各自的 SHA256 文件。
-
-## 10. Git 提交流程
-
-部署逻辑变化必须同时更新本文件及交付包内对应文档。提交前执行：
-
-```bash
-git status --short
-git diff --check
-python3 deploy/linux-docker-offline-deerflow-only/test_release_renderer.py "$(pwd)"
-```
-
-禁止提交真实 `deploy.env`、数据库密码、模型 API Key、运行数据、生成配置、
-Docker 镜像 tar 或最终离线 `.tar.gz`。仓库中的 `deploy.env` 只能包含明确的假地址
-和示例凭据。