跳到主要内容

运行部署技术方案

# 运行部署技术方案

1. 覆盖范围​

运行部署方案负责把 GitHub、控制面、Docusaurus、RAGFlow、Meilisearch 和商业 LLM API 组合成可运行 MVP。

能力技术产品
定时任务GitHub Actions
PR 自动化GitHub Actions + token/App
文档站Docusaurus + 静态托管
智能体/RAG已部署 RAGFlow
RAG 检索RAGFlow dataset / RAG 索引（向量存储优先评估 pgvector）
全文搜索Meilisearch
问答 APILLM-WIKI wrapper + RAGFlow
智能体访问 APILLM-WIKI Agent Access API/tool adapter

2. 如何购买或获取​

MVP 购买/获取清单：

项目方式
GitHubFree/Team 起步，私有仓库和团队治理建议 Team
RAGFlow已部署，复用现有环境
Docusaurus开源，无需购买
Meilisearch自建或 Cloud，MVP 可自建
商业 LLM API按 token 付费
静态托管GitHub Pages 或其他静态托管

2.1 MVP 默认部署组合​

默认组合用于把方案落到可执行实施，不影响后续替换。

能力默认实施
自动化GitHub Actions
文档站Docusaurus build + GitHub Pages 或等价静态托管
Answer API / Agent Access API轻量容器服务，部署在能访问 RAGFlow 的网络内
RAG/Agent已部署 RAGFlow
全文搜索自建 Meilisearch Docker 或托管 Meilisearch
模型RAGFlow-managed commercial LLM，优先 OpenAI-compatible endpoint
SecretsGitHub Actions Secrets + 服务运行环境变量

如果 RAGFlow 在内网，默认采用“API 服务靠近 RAGFlow”的部署方式：外部只访问 Answer API / Agent Access API，不直接访问 RAGFlow。

3. 如何开发​

MVP 运行形态：

GitHub Actions
  -> sync_sources.py
  -> validate_docs.py
  -> generate_impact_report.py
  -> publish_docusaurus.py
  -> index_meilisearch.py
  -> ragflow_adapter.py
  -> agent_access_api.py

Long-running services
  -> RAGFlow existing deployment
  -> Meilisearch
  -> optional LLM-WIKI Answer API / Agent Access API

如果早期不建设长驻 Answer API 和 Agent Access API，可以先由 Docusaurus 前端或内部智能体调用一个轻量 serverless/API wrapper，再由 wrapper 调 RAGFlow、Meilisearch 和 GitHub Issues。

4. 如何部署​

4.1 GitHub Actions 部署​

工作流部署在 .github/workflows/。

必须包含：

  • 同步 workflow。
  • 发布校验 workflow。
  • 索引更新 workflow。
  • 手动触发 Agent workflow。

默认 workflow：

Workflow触发运行位置关键输出
docs-sync.ymlschedule / workflow_dispatchGitHub ActionsSync PR、source-changes.json
docs-publish.ymlPR / mainGitHub ActionsDocusaurus build、impact report、site manifest
docs-index.ymlmain 发布成功后GitHub Actions 或 self-hosted runnerRAGFlow / Meilisearch index manifest
docs-agent.ymlworkflow_dispatch / Issue labelGitHub Actions 或内网 runnerRelease PR

4.2 服务部署​

服务MVP 部署建议
RAGFlow复用已有部署
MeilisearchDocker 自建或托管实例
Docusaurus静态托管
Answer API可先 serverless，后续容器化
Agent Access API可先 serverless，后续容器化或扩展为 MCP server

默认服务拓扑：

Internet / internal users
  -> Docusaurus static site
  -> Answer API / Agent Access API
       -> RAGFlow API
       -> Meilisearch API
       -> GitHub Issues API

GitHub Actions
  -> GitHub source repos
  -> Docusaurus build
  -> static hosting publish
  -> Meilisearch indexing
  -> RAGFlow dataset indexing

部署原则：

  • Docusaurus 静态站可以部署在 GitHub Pages、对象存储/CDN、Vercel/Netlify 或内网静态服务器。
  • Answer API / Agent Access API 必须部署在能访问 RAGFlow 的网络环境。
  • 如果 GitHub-hosted runner 无法访问 RAGFlow，应使用 self-hosted runner 或内部部署的索引代理。
  • Meilisearch 如果自建，必须启用 master key，并限制公网访问。

4.3 网络部署约束​

  • GitHub Actions 必须能访问 GitHub 来源项目。
  • 索引 workflow 必须能访问 Meilisearch 和 RAGFlow。
  • Answer API 必须能访问 RAGFlow。
  • Agent Access API 必须能访问 RAGFlow、Meilisearch 和 GitHub Issues。
  • 如果 RAGFlow 在内网，必须提供安全访问通道或使用 self-hosted runner。

5. 如何配置​

统一环境变量：

GH_DOCS_TOKEN
RAGFLOW_BASE_URL
RAGFLOW_API_KEY
RAGFLOW_DATASET_ID
RAGFLOW_AGENT_ID
MEILI_URL
MEILI_MASTER_KEY
MEILI_INDEX
AGENT_ACCESS_TOKEN
MODEL_PROVIDER
MODEL_API_KEY

5.1 环境变量分层​

GitHub Actions Secrets：

GH_DOCS_TOKEN
RAGFLOW_BASE_URL
RAGFLOW_API_KEY
RAGFLOW_DATASET_APPROVED_ID
RAGFLOW_DATASET_WORKING_ID
RAGFLOW_AGENT_ID
MEILI_URL
MEILI_MASTER_KEY
MEILI_INDEX
STATIC_DEPLOY_TOKEN

Answer API / Agent Access API 运行环境：

RAGFLOW_BASE_URL
RAGFLOW_API_KEY
MEILI_URL
MEILI_SEARCH_KEY
GITHUB_APP_ID
GITHUB_APP_PRIVATE_KEY
AGENT_ACCESS_TOKEN_*
MODEL_PROVIDER=ragflow-managed

RAGFlow 环境或控制台：

MODEL_API_BASE
MODEL_API_KEY
MODEL_CHAT_MODEL
MODEL_EMBEDDING_MODEL

约束：

  • MEILI_MASTER_KEY 只给索引更新任务使用，前端和 Agent Access 不使用 master key。
  • AGENT_ACCESS_TOKEN_* 按智能体分配，不共用单个万能 token。
  • 模型 key 默认只配置在 RAGFlow。
  • 所有 Secrets 不写入仓库、不输出到日志。

统一配置文件：

config/sources.yaml
config/site.yaml
config/publish.yaml
config/ragflow.yaml
config/agent-access.yaml
config/index.yaml
config/model-policy.yaml

6. 如何使用​

6.1 日常同步​

  1. GitHub Actions 定时运行。
  2. 同步来源项目文档到 publish/**。
  3. 生成 Sync PR。
  4. 人工处理冲突并合并。

6.2 文档迭代​

  1. Issue 或人工触发 Agent workflow。
  2. LLM-WIKI 调用 RAGFlow。
  3. RAGFlow 生成结构化建议或内容草稿。
  4. AgentBridge 校验输出并生成 Git diff。
  5. LLM-WIKI 创建 Release PR。
  6. 生成发布影响报告并写入 PR summary。
  7. 人工审批后合并。

6.3 发布与索引​

  1. Release PR 合并到 main。
  2. Docusaurus build。
  3. 生成 site-manifest 并执行关键 URL 对账。
  4. 发布静态站点。
  5. 更新 Meilisearch 和 RAGFlow dataset。
  6. 问答服务使用新索引。

6.4 智能体访问​

  1. 智能体携带 token、caller 和 scope 调用 Agent Access API。
  2. Agent Access API 校验权限和 scope。
  3. 读取类工具调用 RAGFlow、Meilisearch 或发布目录元数据。
  4. 写入类工具只能创建 GitHub Issue、反馈记录或触发受控文档迭代任务。
  5. 所有正式文档改动仍然进入 Release PR。

7. 观测和运维​

对象观测方式
GitHub Actionsworkflow run、日志、失败通知
RAGFlow平台日志、任务状态、API 错误
Meilisearchtask 状态、index 文档数
Docusaurusbuild 日志、站点访问
Agent Access APIrequestId、caller、scope、tool、状态码
LLM APItoken 用量、错误率、预算告警
发布影响publish-impact-report.json、PR summary
展示层漂移site-manifest.json、URL/hash 对账报告

8. 验收标准​

  • 一次来源文档变更能自动进入 Sync PR。
  • 一次文档改进任务能通过 RAGFlow 生成建议，并由 AgentBridge 转成 Release PR。
  • Release PR 合并后文档站更新。
  • PR 中能看到发布影响报告，发布后能生成 site manifest。
  • 索引更新后 Meilisearch 搜索和 RAGFlow 问答能返回新内容。
  • 智能体能通过 Agent Access API 获取上下文、提问并提交反馈。
  • 任一外部服务失败时，不会产生半发布状态。
  • GitHub Actions 能完成 Docusaurus build。
  • Answer API / Agent Access API 能访问 RAGFlow、Meilisearch 和 GitHub Issues。
  • 如果 RAGFlow 在内网，self-hosted runner 或内部 API 服务路径已验证。
  • 前端或智能体不能直接拿到 RAGFlow、Meilisearch master key 或模型 key。
编辑此页
◇对此页面有疑问？

问答功能将在后续接入 Answer API。当前可通过页面底部的反馈链接提交问题。

页面来源草稿
来源项目kunora-wiki
分支docs-publish
路径technology/components/kunora-wiki/product/07-mvp-technical-solution/08-runtime-deployment.md