7.6 · CI/CD 与发布流程（CI/CD and Release Process）

CI/CD 与发布流程（中文译文）

此页面内容来自 DeepWiki 重组后的对应页面（来源：10-2.zh.md）

翻译时间：2026-05-27T12:17:56.056Z

翻译模型：deepseek-chat

项目：LightRAG (lightrag)

---

CI/CD 工作流与发布流程

相关源文件

以下文件用于生成此 Wiki 页面：

• .gitattributes
• .github/CONTRIBUTING.md
• .github/ISSUE_TEMPLATE/bug_report.yml
• .github/ISSUE_TEMPLATE/config.yml
• .github/ISSUE_TEMPLATE/feature_request.yml
• .github/ISSUE_TEMPLATE/question.yml
• .github/dependabot.yml
• .github/pull_request_template.md
• .github/workflows/copilot-setup-steps.yml
• .github/workflows/docker-build-lite.yml
• .github/workflows/docker-build-manual.yml
• .github/workflows/docker-publish.yml
• .github/workflows/linting.yaml
• .github/workflows/pypi-publish.yml
• .github/workflows/stale.yaml
• .github/workflows/tests.yml
• .pre-commit-config.yaml
• lightrag/_version.py
• tests/conftest.py

LightRAG 项目采用基于 GitHub Actions 的健壮 CI/CD 管线，以确保代码质量、自动化多平台分发（PyPI 和 Docker），并维护依赖健康。发布流程整合了 Python 核心和基于 React 的 WebUI 的版本管理。

质量保证工作流

项目通过对 main 和 dev 分支的每次推送和拉取请求执行自动化的代码检查和单元测试，来强制执行代码标准。

代码检查与格式化

linting.yaml 工作流利用 pre-commit 执行多个钩子：

• 标准钩子：trailing-whitespace、end-of-file-fixer 和 requirements-txt-fixer .pre-commit-config.yaml:5-9。
• Ruff：用于代码格式化（ruff-format）和启用自动修复的代码检查（ruff --fix）.pre-commit-config.yaml:16-19。
• 排除项：所有代码检查钩子均排除 lightrag/api/webui/ 目录，因为该目录包含编译后的或二进制资源 .pre-commit-config.yaml:6,8,10,17,20。

如果代码检查失败，工作流会使用 actions/github-script@v9 在拉取请求中发布一条包含本地修复说明的评论 .github/workflows/linting.yaml:74-134。

自动化测试

tests.yml 工作流在多个 Python 版本（当前为 3.12 和 3.14）上执行测试套件 .github/workflows/tests.yml:18。

• 离线模式：默认情况下，CI 仅运行标记有 @pytest.mark.offline 标记的测试，以避免外部 API 或数据库依赖 .github/workflows/tests.yml:46。
• 封闭环境：tests/conftest.py 中的 _hermetic_mineru_env 夹具会剥离 MINERU_API_MODE 和 LIGHTRAG_PARSER 等环境变量，以防止本地开发者配置泄露到 CI 环境中 tests/conftest.py:11-43。
• 制品：测试结果和 .pytest_cache 会上传为制品，保留 7 天 .github/workflows/tests.yml:50-56。

CI 质量控制流程

graph TD
    Trigger["推送 / 拉取请求到 main/dev"] --> Lint["linting.yaml"]
    Trigger --> Tests["tests.yml"]

    subgraph "代码检查钩子"
    Lint --> Ruff["Ruff 格式化与修复"]
    Lint --> Hooks["Pre-commit 钩子"]
    end

    subgraph "测试执行"
    Tests --> Matrix["Python 3.12 / 3.14"]
    Matrix --> Pytest["pytest -m offline"]
    end

    Ruff -- "失败" --> PRComment["向拉取请求发布修复说明"]
    Pytest -- "成功" --> Artifacts["上传 test-results.xml"]

来源：.github/workflows/linting.yaml:1-134、.github/workflows/tests.yml:1-57、tests/conftest.py:1-60。

发布与分发流程

发布流程由 GitHub Release 的发布触发。它涉及同步版本更新、构建 WebUI，以及发布到 PyPI 和 GHCR。

版本管理机制

版本的唯一真实来源是 lightrag/_version.py lightrag/_version.py:3。在发布工作流期间，会调用 scripts/release/set_version.py 脚本将此文件与 Git 标签同步 .github/workflows/pypi-publish.yml:67。

PyPI 发布

pypi-publish.yml 工作流处理 Python 包的分发：

1. WebUI 构建：使用 oven-sh/setup-bun 安装依赖并构建 lightrag_webui/ 中的前端 .github/workflows/pypi-publish.yml:22-31。
2. 验证：在继续之前确认 lightrag/api/webui/index.html 存在 .github/workflows/pypi-publish.yml:35-38。
3. 分发构建：使用 python -m build 创建源码分发包和 Wheel 分发包 .github/workflows/pypi-publish.yml:73。
4. 上传：使用可信发布（OIDC）发布到 PyPI .github/workflows/pypi-publish.yml:99。

Docker 发布

项目维护两个主要的 Docker 工作流：

• docker-publish.yml：在发布时触发。它构建多平台镜像（linux/amd64、linux/arm64）并使用 cosign 签名 .github/workflows/docker-publish.yml:84-111。
• docker-build-lite.yml：一个手动工作流（workflow_dispatch），使用 Dockerfile.lite 构建镜像的"精简"版本 .github/workflows/docker-build-lite.yml:84。

发布数据流

sequenceDiagram
    participant Dev as 开发者
    participant Git as GitHub 标签/发布
    participant UI as Bun (WebUI 构建)
    participant PyPI as PyPI 注册表
    participant GHCR as GitHub 容器注册表

    Dev->>Git: 创建发布 (v1.5.0)
    Git->>UI: 触发 pypi-publish.yml
    UI->>UI: bun run build
    UI->>UI: 复制资源到 lightrag/api/webui/
    Git->>PyPI: 构建并上传 Wheel (lightrag-hku)
    Git->>GHCR: 构建并推送 Docker (latest & v1.5.0)
    GHCR->>GHCR: 使用 cosign 签名镜像

来源：.github/workflows/pypi-publish.yml:1-102、.github/workflows/docker-publish.yml:1-121、lightrag/_version.py:1-5。

依赖与维护

Dependabot 配置

dependabot.yml 文件管理自动化更新，并采用特定的分组策略以减少拉取请求噪音：

• Python (pip)：按类别分组：llm-providers、storage、data-processing 和 web-framework .github/dependabot.yml:47-95。
• 前端 (bun)：分组为 react、ui-components、graph-viz 和 build-tools .github/dependabot.yml:142-187。
• GitHub Actions：所有更新被分组到一个每周拉取请求中 .github/dependabot.yml:11-16。

过期问题管理

stale.yaml 工作流每天运行，以识别不活跃的问题和拉取请求。

• 问题：在 30 天不活跃后标记为过期，再过 7 天后关闭 .github/workflows/stale.yaml:12-14。
• 拉取请求：在 14 天后标记为过期，再过 7 天后关闭 .github/workflows/stale.yaml:17-19。

手动与辅助工作流

• docker-build-manual.yml：允许开发者从任何分支或提交 SHA 构建和签名测试 Docker 镜像 .github/workflows/docker-build-manual.yml:35-37。
• copilot-setup-steps.yml：为 GitHub Copilot 代理配置专门的环境，包括一个最小化的前端桩，使服务器无需完整 WebUI 构建即可启动 .github/workflows/copilot-setup-steps.yml:48-52。

来源：.github/dependabot.yml:1-207、.github/workflows/stale.yaml:1-25、.github/workflows/docker-build-manual.yml:1-110、.github/workflows/copilot-setup-steps.yml:1-59。