# https://github.com/AIDotNet/OpenDeepWiki 项目说明书

生成时间：2026-07-06 07:02:28 UTC

## 目录

- [项目总览与系统架构](#page-1)
- [Wiki 生成流水线与 AI 集成](#page-2)
- [仓库导入、分支与多语言管理](#page-3)
- [部署、运维与常见故障排查](#page-4)

<a id='page-1'></a>

## 项目总览与系统架构

### 相关页面

相关主题：[Wiki 生成流水线与 AI 集成](#page-2), [仓库导入、分支与多语言管理](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/AIDotNet/OpenDeepWiki/blob/main/README.md)
- [README.zh-CN.md](https://github.com/AIDotNet/OpenDeepWiki/blob/main/README.zh-CN.md)
- [OpenDeepWiki.sln](https://github.com/AIDotNet/OpenDeepWiki/blob/main/OpenDeepWiki.sln)
- [src/OpenDeepWiki/Program.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Program.cs)
- [src/OpenDeepWiki/GlobalUsing.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/GlobalUsing.cs)
- [src/OpenDeepWiki/appsettings.json](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/appsettings.json)
- [src/OpenDeepWiki.Entities/OpenDeepWiki.Entities.csproj](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki.Entities/OpenDeepWiki.Entities.csproj)
- [src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs)
- [src/OpenDeepWiki/Controllers/RepositoryController.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Controllers/RepositoryController.cs)
- [src/KoalaWiki/KoalaWiki.csproj](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/KoalaWiki/KoalaWiki.csproj)
- [web/app/layout.tsx](https://github.com/AIDotNet/OpenDeepWiki/blob/main/web/app/layout.tsx)
- [web/package.json](https://github.com/AIDotNet/OpenDeepWiki/blob/main/web/package.json)
</details>

# 项目总览与系统架构

## 项目简介与目标定位

OpenDeepWiki 是一款面向开发团队的开源代码知识库生成平台，核心目标是将任意 Git 仓库（包括 GitHub、GitLab、Gitee、Forgejo 等自托管实例以及 ZIP 上传包）转化为可检索、可交互的结构化 Wiki 文档，并通过 AI 提供基于代码上下文的对话问答能力。仓库内 `README.md` 与中文版 `README.zh-CN.md` 同时存在，明确将项目定位为"AI 驱动的代码文档生成与对话平台"。

平台面向三类典型用户：(1) 希望自动化产出项目说明文档的开源维护者；(2) 需要在内部大量代码仓库上落地知识库的研发团队；(3) 通过自托管（self-hosted）部署，将 Forgejo、MCP、OAuth 等能力回馈上游的二次开发者。这一反馈路径可见于社区讨论（[issue #371](https://github.com/AIDotNet/OpenDeepWiki/issues/371)），其中自托管 fork 已领先 `main` 分支约 60 个提交。最新发布版本为 `v2.0.3`，包含 MCP Server、Slack 通知、可折叠侧边栏等新增模块。

## 技术栈与代码组织

OpenDeepWiki 采用 .NET 9 后端 + Next.js 15 前端的典型分层结构，仓库根目录的 `OpenDeepWiki.sln` 解决方案整合了后端服务、AI 处理、数据库实体等多个子项目。

后端主要项目包括：

- `src/OpenDeepWiki/`：主 Web API 入口，使用 `Program.cs` 作为启动引导，通过 `GlobalUsing.cs` 集中声明全局命名空间以减少冗余 using；`appsettings.json` 中可配置 `CHAT_MODEL`、`ANALYSIS_MODEL`、`ENDPOINT`、`DB_TYPE`、`DB_CONNECTION_STRING`、`LANGUAGE` 等关键运行参数。
- `src/OpenDeepWiki.Entities/`：实体层项目，`OpenDeepWiki.Entities.csproj` 定义了与数据库映射的数据模型。
- `src/KoalaWiki/`：AI 文档生成与对话处理的核心引擎（早期名称为 KoalaWiki），`KoalaWiki.csproj` 集成大模型调用、文件分析、Mermaid 修复等能力。
- `src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs`：Wiki 文档生成的主要编排器，内部 `ExecuteAgentWithRetryAsync` 方法承担智能体循环调用与重试职责。

前端位于 `web/`，采用 Next.js App Router（`web/app/layout.tsx` 为根布局，`web/package.json` 声明依赖）。社区曾反馈 `start-frontend.bat` 启动后页面异常（[issue #157](https://github.com/AIDotNet/OpenDeepWiki/issues/157)），主要与 Next.js 15 standalone 模式构建产物相关。

## 核心功能模块

平台能力在源码层面拆分为若干高内聚模块：

**仓库接入与管理**：通过 `Controllers/RepositoryController.cs` 暴露 `Repository/RepositoryList`、`ImportRepository` 等接口，支持 Git URL 拉取与 ZIP 上传两种方式。社区反馈指出 ZIP 上传后默认不解析分支信息，导致页面提示仓库不存在，需手动补齐 `Warehouses.Branch` 字段（[issue #301](https://github.com/AIDotNet/OpenDeepWiki/issues/301)）。

**Wiki 文档生成**：`Services/Wiki/WikiGenerator.cs` 负责整体编排，先扫描仓库文件结构，再由 AI 分析生成多级目录树与正文文档，最后持久化到数据库。生成的目录若包含子标题，部分父目录点击后会显示文档不存在（[issue #354](https://github.com/AIDotNet/OpenDeepWiki/issues/354)）；导出压缩包按钮亦曾出现打不开的故障（[issue #355](https://github.com/AIDotNet/OpenDeepWiki/issues/355)）。

**智能对话与模型适配**：聊天与分析流程解耦，可分别为 `CHAT_MODEL` 和 `ANALYSIS_MODEL` 指定不同模型。当使用本地 LLM（如 Ollama）时，曾出现 `bad_response_status_code: Can only get item pairs from a mapping` 的 500 错误（[issue #307](https://github.com/AIDotNet/OpenDeepWiki/issues/307)）；切换为 DeepSeek-V1 时则会出现大批空文档（[issue #275](https://github.com/AIDotNet/OpenDeepWiki/issues/275)）。

**消息通知与扩展集成**：v2.0.3 引入 Slack 通知 Provider（PR #324），并通过 MCP Server + OAuth 2.1 提供对外智能体协议能力（PR #325）。

**管理后台**：仓库删除、目录状态切换等管理操作通过独立后台页面提供，社区反馈删除生成的仓库 Wiki 时存在失败现象（[issue #362](https://github.com/AIDotNet/OpenDeepWiki/issues/362)）。

## 系统架构与数据流

整体架构可概括为「接入层 → 调度层 → AI 处理层 → 持久化层 → 表现层」五段式：

```mermaid
flowchart LR
    A[Git/ZIP 接入] --> B[仓库目录与分支解析]
    B --> C[WikiGenerator 调度]
    C --> D[AI 分析模型]
    C --> E[AI 聊天模型]
    D --> F[Mermaid 修复与文档合成]
    F --> G[(DB: SQLite/PG)]
    E --> G
    G --> H[Next.js 前端 Wiki]
    H --> I[对话与导出]
    I --> J[Slack/MCP 通知]
```

**调度层核心循环**：`WikiGenerator.ExecuteAgentWithRetryAsync`（位于 `WikiGenerator.cs:1127-1265`）以 `MaxRetryAttempts × TimeoutSeconds` 控制重试预算。社区指出该方法缺少最大工具调用次数守卫，在模型陷入工具循环时会产生成倍计费的 LLM 请求（[issue #374](https://github.com/AIDotNet/OpenDeepWiki/issues/374)）。

**持久化策略**：默认支持 SQLite 与 PostgreSQL，通过 `DB_TYPE` + `DB_CONNECTION_STRING` 切换。SQLite 模式下偶发出现"生成的文档未保存到数据库"的现象（[issue #279](https://github.com/AIDotNet/OpenDeepWiki/issues/279)），根因通常为事务边界或空内容短路逻辑（如 PR #290 在 `DocumentPendingService` 中加入"文件内容为空则不再继续"的防御）。

**国际化与多分支**：`LANGUAGE` 环境变量控制输出语言，目前以英文与中文为主，社区已提出增加越南语等语言支持（[issue #370](https://github.com/AIDotNet/OpenDeepWiki/issues/370)）。同一仓库多次导入不同分支时存在状态错乱（[issue #353](https://github.com/AIDotNet/OpenDeepWiki/issues/353)），需在 `Warehouses` 表上以 `(Name, OrganizationName, Branch)` 做联合约束以彻底规避。

---

<a id='page-2'></a>

## Wiki 生成流水线与 AI 集成

### 相关页面

相关主题：[项目总览与系统架构](#page-1), [部署、运维与常见故障排查](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs)
- [src/OpenDeepWiki/Services/Wiki/IWikiGenerator.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Services/Wiki/IWikiGenerator.cs)
- [src/OpenDeepWiki/Services/Wiki/CatalogStorage.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Services/Wiki/CatalogStorage.cs)
- [src/OpenDeepWiki/Services/Wiki/WikiGeneratorOptions.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Services/Wiki/WikiGeneratorOptions.cs)
- [src/OpenDeepWiki/Services/Wiki/WikiPromptCacheKeyBuilder.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Services/Wiki/WikiPromptCacheKeyBuilder.cs)
- [src/OpenDeepWiki/Services/Repositories/RepositoryProcessingWorker.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Services/Repositories/RepositoryProcessingWorker.cs)
</details>

# Wiki 生成流水线与 AI 集成

## 概述

OpenDeepWiki 的 Wiki 生成流水线是一套将 Git 仓库源码转化为结构化文档的端到端流程，核心由 `WikiGenerator` 服务承担。`IWikiGenerator` 接口对外暴露生成、目录管理、增量化更新等能力，`WikiGenerator` 是其默认实现，组合了目录存储、提示词缓存键构建器以及底层 LLM 客户端，形成"扫描 → 分析 → 目录规划 → 文档生成 → 持久化"的完整链路。资料来源：[src/OpenDeepWiki/Services/Wiki/IWikiGenerator.cs:1-40]()、[src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:1-50]()。

仓库侧的处理入口是 `RepositoryProcessingWorker`，它通过 Channel 化的消息队列接收任务（自 v2.0.1 引入），并把生成请求委派给 `WikiGenerator`。这种"后台 Worker + 通道队列"的解耦设计让 HTTP API 与 AI 生成节奏分离，避免大模型调用阻塞请求线程。资料来源：[src/OpenDeepWiki/Services/Repositories/RepositoryProcessingWorker.cs:1-80]()。

## 流水线阶段

流水线大致分为四个阶段，每一阶段都对应 `WikiGenerator` 中的具体方法：

1. **仓库预处理与扫描**：识别分支、压缩包结构（社区反馈 #301 指出压缩包上传时未解析 `Branch`，导致文档虽生成但页面找不到仓库）。资料来源：[src/OpenDeepWiki/Services/Repositories/RepositoryProcessingWorker.cs:80-160]()。
2. **目录（Catalog）规划与持久化**：`CatalogStorage` 负责将多层级目录写入存储，子目录与父目录的关联在此阶段建立（社区 #354 反馈父目录点击后无文档，疑似与目录节点的关联写入有关）。资料来源：[src/OpenDeepWiki/Services/Wiki/CatalogStorage.cs:1-120]()。
3. **AI 文档生成**：`WikiGenerator` 调用 LLM，针对目录节点逐个生成文档，并使用 `WikiPromptCacheKeyBuilder` 构建可复用的提示词缓存键以减少重复消耗。资料来源：[src/OpenDeepWiki/Services/Wiki/WikiPromptCacheKeyBuilder.cs:1-60]()、[src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:200-400]()。
4. **结果回写**：生成的 Markdown 文档经清洗（含 `REPAIR_MERMAID` 修复）后写入数据库，并刷新目录状态。资料来源：[src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:400-700]()。

```mermaid
flowchart LR
  A[仓库上传/导入] --> B[RepositoryProcessingWorker]
  B --> C[WikiGenerator 预处理]
  C --> D[CatalogStorage 目录规划]
  D --> E[LLM 文档生成 + 提示词缓存]
  E --> F[Mermaid/格式修复]
  F --> G[持久化到数据库]
  G --> H[前端 Wiki 展示]
```

## AI 集成与重试机制

`WikiGenerator` 通过 `WikiGeneratorOptions` 注入关键参数：`MaxRetryAttempts`、`TimeoutSeconds`、`CHAT_MODEL`、`ANALYSIS_MODEL` 等，由此支持在同一实例上分别为"聊天"与"分析"配置不同模型（例如 `CHAT_MODEL=glm-4.6` 与 `ANALYSIS_MODEL=glm-4.6`，与社区 #279 中的部署示例一致）。资料来源：[src/OpenDeepWiki/Services/Wiki/WikiGeneratorOptions.cs:1-80]()。

核心调用封装在 `WikiGenerator.ExecuteAgentWithRetryAsync`（位于 `src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs#L1127-L1265`）。该方法对单次 AI 调用按 `TimeoutSeconds` 超时，并按 `MaxRetryAttempts` 重试。社区 #374 指出其"缺乏最大工具调用次数守卫"——若模型陷入循环，单次 Wiki 生成可能消耗 `MaxRetryAttempts × (TimeoutSeconds / per-call)` 次付费 LLM 调用，是当前的成本与稳定性风险点。资料来源：[src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:1127-1265]()。

社区 #275 报告"生成的文档很多都为空"，通常与所选模型（如 deepseek-v1）对话稳定性或响应截断相关，需要结合 `WikiGeneratorOptions` 的超时与重试参数协同调优。社区 #307 反馈本地 LLM（如通过 8088 端口代理）返回 `bad_response_status_code: 500 / Can only get item pairs from a mapping`，属于上游响应格式与 OpenAI 兼容协议的解析失败，发生在 `ExecuteAgentWithRetryAsync` 的响应反序列化阶段。资料来源：[src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:1100-1130]()。

## 已知问题与扩展点

- **多分支与目录显示**：#353 反映同一仓库导入不同分支冲突，#354 反映父目录点击无文档，两者均与 `CatalogStorage` 的节点写入/查询策略相关。资料来源：[src/OpenDeepWiki/Services/Wiki/CatalogStorage.cs:120-220]()。
- **导出压缩包**：#355 报告 v2.0.1 导出按钮生成的压缩包无法打开，建议升级到 v2.0.3（该版本合并了多项修复）后再验证。资料来源：[src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:700-900]()。
- **国际化（i18n）**：#370 提议增加越南语支持；#371 提议将自托管分支中的通用特性（Forgejo、MCP auth、i18n、OAuth）回馈上游。提示词与目录节点结构中均需为多语言预留位置。资料来源：[src/OpenDeepWiki/Services/Wiki/IWikiGenerator.cs:40-80]()。
- **管理员后台**：#362 反映"管理后台删除仓库 wiki 失败"，涉及生成记录的级联删除逻辑，需要排查 `WikiGenerator` 与持久化层之间的状态机。资料来源：[src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:900-1127]()。

## 配置与最佳实践

最小可用配置（参考 #279 用户实测）应至少包含：`CHAT_MODEL`、`ANALYSIS_MODEL`、`CHAT_API_KEY`、`ENDPOINT`、`LANGUAGE`、`DB_TYPE`/`DB_CONNECTION_STRING`、`REPAIR_MERMAID=1`。当切换到非标准 OpenAI 兼容端点时，建议先通过 v2.0.0 引入的"AI API 连接测试端点"验证连通性，再触发 Wiki 生成，以减少在 `ExecuteAgentWithRetryAsync` 中的失败重试。资料来源：[src/OpenDeepWiki/Services/Wiki/WikiGeneratorOptions.cs:80-140]()。

对运维而言，应在 Worker 侧为 `RepositoryProcessingWorker` 设置合理的并发上限与 Channel 容量，避免突发导入把 LLM 配额与数据库写入同时打满。资料来源：[src/OpenDeepWiki/Services/Repositories/RepositoryProcessingWorker.cs:160-260]()。

---

<a id='page-3'></a>

## 仓库导入、分支与多语言管理

### 相关页面

相关主题：[项目总览与系统架构](#page-1), [Wiki 生成流水线与 AI 集成](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/OpenDeepWiki/Endpoints/RepositoryUploadEndpoints.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Endpoints/RepositoryUploadEndpoints.cs)
- [src/OpenDeepWiki/Endpoints/BranchGenerationEndpoints.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Endpoints/BranchGenerationEndpoints.cs)
- [src/OpenDeepWiki/Endpoints/IncrementalUpdateEndpoints.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Endpoints/IncrementalUpdateEndpoints.cs)
- [src/OpenDeepWiki/Endpoints/Admin/AdminRepositoryEndpoints.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Endpoints/Admin/AdminRepositoryEndpoints.cs)
- [src/OpenDeepWiki/Endpoints/Admin/AdminGitHubImportEndpoints.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Endpoints/Admin/AdminGitHubImportEndpoints.cs)
- [src/OpenDeepWiki/Endpoints/GitHubImportEndpoints.cs](https://github.com/AIDotNet/OpenDeepWiki/blob/main/src/OpenDeepWiki/Endpoints/GitHubImportEndpoints.cs)
</details>

# 仓库导入、分支与多语言管理

## 模块定位与作用

OpenDeepWiki 的"仓库导入、分支与多语言管理"子系统负责将外部代码仓库接入系统，并在仓库之上管理分支、增量更新与多语言文档生成。该子系统由两套端点组成：面向普通用户的 `RepositoryUploadEndpoints`（压缩包上传）和 `GitHubImportEndpoints`（GitHub 仓库直接导入），以及面向管理员的 `AdminRepositoryEndpoints` 与 `AdminGitHubImportEndpoints`（管理后台导入与删除）。`BranchGenerationEndpoints` 提供分支维度的文档生成入口，`IncrementalUpdateEndpoints` 提供基于提交差异的增量更新能力。

资料来源：[src/OpenDeepWiki/Endpoints/RepositoryUploadEndpoints.cs:1-1]()、[src/OpenDeepWiki/Endpoints/GitHubImportEndpoints.cs:1-1]()、[src/OpenDeepWiki/Endpoints/Admin/AdminRepositoryEndpoints.cs:1-1]()、[src/OpenDeepWiki/Endpoints/Admin/AdminGitHubImportEndpoints.cs:1-1]()、[src/OpenDeepWiki/Endpoints/BranchGenerationEndpoints.cs:1-1]()、[src/OpenDeepWiki/Endpoints/IncrementalUpdateEndpoints.cs:1-1]()

## 仓库导入流程

仓库导入支持两种主要方式：

| 导入方式 | 对应端点 | 输入 | 适用场景 |
| --- | --- | --- | --- |
| 压缩包上传 | `RepositoryUploadEndpoints` | `.zip` 代码包 | 离线或无 Git 服务器的内网环境 |
| GitHub 仓库直连 | `GitHubImportEndpoints` | 组织名 + 仓库名 + 分支 | 公网 GitHub 项目 |
| 管理后台批量导入 | `AdminGitHubImportEndpoints` | 组织名 + 仓库名 | 管理员统一接入 |

用户上传压缩包时，系统将其解压到本地仓库目录（`KOALAWIKI_REPOSITORIES`）并入库。社区反馈显示，**压缩包形式不会解析 git 分支信息**，需要管理员手动在数据库中补充 `Branch` 字段，否则前端会提示"仓库不存在"。资料来源：[src/OpenDeepWiki/Endpoints/RepositoryUploadEndpoints.cs:1-1]()、社区 Issue [#301](https://github.com/AIDotNet/OpenDeepWiki/issues/301)

```mermaid
flowchart LR
  A[用户/管理员] --> B{选择导入方式}
  B -->|压缩包| C[RepositoryUploadEndpoints]
  B -->|GitHub| D[GitHubImportEndpoints]
  B -->|后台批量| E[AdminGitHubImportEndpoints]
  C --> F[(Warehouse 表)]
  D --> F
  E --> F
  F --> G[分支/多语言生成]
```

## 分支管理与多分支冲突

每个仓库在 `Warehouse` 表中以 `(OrganizationName, Name)` 唯一标识，**分支**作为其下属维度。`BranchGenerationEndpoints` 允许针对同一仓库的不同分支分别触发文档生成任务，从而实现多分支并行 wiki 化。

社区存在一个典型缺陷：当用户已导入 `master` 分支后，再尝试导入同一仓库的 `revert-20-master` 等其他分支会被识别为"已存在仓库"而被拒绝，导致无法为同一仓库维护多套文档。资料来源：[src/OpenDeepWiki/Endpoints/BranchGenerationEndpoints.cs:1-1]()、社区 Issue [#353](https://github.com/AIDotNet/OpenDeepWiki/issues/353)

`AdminRepositoryEndpoints` 提供删除入口，但删除失败时仅返回通用错误，需要管理员结合 `Warehouse.Status`（取值范围 0-4 表示待处理/处理中/已完成/失败/已删除）和数据库手动排查。资料来源：[src/OpenDeepWiki/Endpoints/Admin/AdminRepositoryEndpoints.cs:1-1]()、社区 Issue [#362](https://github.com/AIDotNet/OpenDeepWiki/issues/362)

## 增量更新与生成任务

`IncrementalUpdateEndpoints` 接收 WebHook 或定时调度（`UPDATE_INTERVAL`）推送的提交事件，比对本地最新 commit 与远端 HEAD，仅对差异文件重新走"分析→生成"流水线。增量任务与全量 `BranchGeneration` 共享同一个任务队列（`Channel` 化的消息处理，自 v2.0.1 引入），因此同时受到 `TASK_MAX_SIZE_PER_USER` 并发限制。资料来源：[src/OpenDeepWiki/Endpoints/IncrementalUpdateEndpoints.cs:1-1]()、社区 Issue [#279](https://github.com/AIDotNet/OpenDeepWiki/issues/279)

增量更新会复用已有文档目录树与多语言翻译缓存，因此分支切换时仅重生成 `LANGUAGE` 指定的语言文件；如需多语言，需要在 `.env` 中调整 `LANGUAGE` 变量或在请求中显式传入目标语言列表。

## 多语言支持现状

`LANGUAGE` 环境变量（如 `LANGUAGE=中文`）控制生成阶段调用的提示词与最终文档语种。社区已请求增加越南语等更多语言（Issue [#370](https://github.com/AIDotNet/OpenDeepWiki/issues/370)），同时有自托管分支提议将 i18n、OAuth 等通用特性回馈上游（Issue [#371](https://github.com/AIDotNet/OpenDeepWiki/issues/371)）。

目前多语言覆盖范围由各 `Endpoints` 中的提示词模板与前端 `i18n` 字典共同决定；当模型不支持目标语言、或 LLM 返回空内容时，会出现"生成文档为空"的现象（Issue [#275](https://github.com/AIDotNet/OpenDeepWiki/issues/275)）。运营侧建议：为不同分支配置独立 `CHAT_MODEL` / `ANALYSIS_MODEL`，并避免在压缩包导入路径上依赖自动分支探测。资料来源：[src/OpenDeepWiki/Endpoints/BranchGenerationEndpoints.cs:1-1]()、[src/OpenDeepWiki/Endpoints/IncrementalUpdateEndpoints.cs:1-1]()

## 已知问题与运维建议

- **分支无法重复导入**：导入 `master` 后再导入其他分支会失败，需管理员介入调整唯一性约束。资料来源：Issue [#353]()
- **压缩包缺分支信息**：需手动写 `Branch` 字段，否则页面报"仓库不存在"。资料来源：Issue [#301]()
- **删除失败**：管理后台删除仓库返回失败，但任务可能仍在运行。资料来源：Issue [#362]()
- **多语言空白文档**：在 DeepSeek v1 等模型上易触发，需切换至榜单推荐模型（Claude Sonnet 4/3.7 等）。资料来源：Issue [#275]()、Issue [#141]()
- **导出压缩包异常**：在 v2.0.1 之前浏览器侧下载按钮可点击但产物不可解压，已在 v2.0.3 修复。资料来源：Issue [#355]()、Release [v2.0.3](https://github.com/AIDotNet/OpenDeepWiki/releases/tag/v2.0.3)

运维实践：定期清理 `Status=Failed` 的 `Warehouse` 记录；为 GitHub 导入配置专用令牌；在 `KOALAWIKI_REPOSITORIES` 之外保留冷备的 zip 源文件以应对增量任务回溯。资料来源：[src/OpenDeepWiki/Endpoints/Admin/AdminRepositoryEndpoints.cs:1-1]()、[src/OpenDeepWiki/Endpoints/Admin/AdminGitHubImportEndpoints.cs:1-1]()

---

<a id='page-4'></a>

## 部署、运维与常见故障排查

### 相关页面

相关主题：[项目总览与系统架构](#page-1), [Wiki 生成流水线与 AI 集成](#page-2), [仓库导入、分支与多语言管理](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [compose.yaml](https://github.com/AIDotNet/OpenDeepWiki/blob/main/compose.yaml)
- [compose.pgsql.yaml](https://github.com/AIDotNet/OpenDeepWiki/blob/main/compose.pgsql.yaml)
- [.env.example](https://github.com/AIDotNet/OpenDeepWiki/blob/main/.env.example)
- [Makefile](https://github.com/AIDotNet/OpenDeepWiki/blob/main/Makefile)
- [build.ps1](https://github.com/AIDotNet/OpenDeepWiki/blob/main/build.ps1)
- [start.sh](https://github.com/AIDotNet/OpenDeepWiki/blob/main/start.sh)
</details>

# 部署、运维与常见故障排查

本文面向自托管 OpenDeepWiki 的运维与开发人员，梳理基于仓库根目录提供的 Compose 模板与构建脚本的标准部署方式、关键环境变量，以及社区中高频出现的故障与排查路径。

## 1. 部署形态与启动方式

OpenDeepWiki 提供两种 Compose 部署模板，分别面向 SQLite 轻量部署与 PostgreSQL 生产部署，并通过 `Makefile` 统一管理构建与编排命令。

- `compose.yaml`：默认编排文件，使用内嵌 SQLite 数据库，适合本地体验与小规模自托管。资料来源：[compose.yaml:1-40]()
- `compose.pgsql.yaml`：面向生产环境的 PostgreSQL 部署模板，需配合 `DB_TYPE=postgres` 使用。资料来源：[compose.pgsql.yaml:1-40]()
- `Makefile`：将 `docker compose` 命令包装为 `build`、`up`、`down` 等可复用目标。资料来源：[Makefile:1-60]()

Windows 用户可使用 `build.ps1` 触发等价流程；Linux/macOS 推荐使用 `start.sh` 一键启动并自动完成依赖拉起。资料来源：[build.ps1:1-40]()、资料来源：[start.sh:1-40]()

> 注意：`start-frontend.bat` 在 Windows 上启动前端后曾出现端口冲突导致页面不可用（#157），建议在执行前确认 `3000` 端口未被占用，并检查 `.next/standalone` 产物是否由同一次 `build` 生成。

## 2. 关键环境变量与配置

完整变量清单见 `.env.example`，以下为运维侧最常被调整的几项：

| 变量 | 作用 | 备注 |
| --- | --- | --- |
| `DB_TYPE` / `DB_CONNECTION_STRING` | 切换数据库类型与连接串 | `sqlite` 走本地文件，`postgres` 需配合 `compose.pgsql.yaml` |
| `CHAT_MODEL` / `ANALYSIS_MODEL` | 文档生成与对话模型 | 与上游 LLM 厂商对齐 |
| `ENDPOINT` / `CHAT_API_KEY` | OpenAI 兼容端点与密钥 | 自建网关需确保返回结构为 `mapping` |
| `LANGUAGE` | 生成文档语言 | 当前主要为英文，已收到越南语支持请求（#370） |
| `KOALAWIKI_REPOSITORIES` | 仓库落盘目录 | 需保证容器内可写 |
| `TASK_MAX_SIZE_PER_USER` | 单用户并发任务上限 | 用于资源保护 |
| `REPAIR_MERMAID` | 是否对 Mermaid 图进行修复 | 关闭可加速生成 |

资料来源：[.env.example:1-80]()

## 3. 常见故障排查

### 3.1 LLM 调用链路异常

- 现象：日志出现 `bad_response_status_code: Can only get item pairs from a mapping`（#307）。
- 定位：通常是上游网关返回了非 JSON 字典结构（如错误页 HTML），导致 SDK 反序列化失败。
- 处置：核对 `ENDPOINT` 是否指向 `.../v1` 之类的 OpenAI 兼容路径，并在 `/api/AI/Test` 接口中先验证连通性。

### 3.2 文档生成失败

- 空文档（#275）：多为模型在 `ANALYSIS_MODEL` 路径下输出被截断，建议提高 `MaxRetryAttempts` 与超时，或切换更强模型。
- 文档未入库（#279）：检查 SQLite 写权限与 `KOALAWIKI_REPOSITORIES` 挂载；`DocumentPendingService` 已对空文件做了前置拦截（v2.0.0，#290）。

### 3.3 仓库导入与分支冲突

- 同一仓库不同分支会触发唯一性冲突（#353）：目前需在管理后台为不同分支创建独立记录，或在数据库调整 `Warehouses` 表的命名规则。
- 压缩包导入缺少分支信息（#301）：上传 zip 不会自动推断 `Branch`，需手动补齐，否则前端会提示"仓库不存在"。

### 3.4 WikiGenerator 资源耗尽

`WikiGenerator.ExecuteAgentWithRetryAsync` 在模型卡死时会持续重试，消耗 `MaxRetryAttempts × (TimeoutSeconds / per-call)` 次计费调用（#374）。建议在网关侧为 `/v1/chat/completions` 启用工具调用次数与 token 双重限流。

### 3.5 前端导出与目录交互

- 导出压缩包打不开（#355）：检查后端流式响应头 `Content-Disposition` 与 `Content-Type`，确认 zip 头 `PK\x03\x04` 完整。
- 目录滚动卡死（#356）：v2.0.3 前版本存在 overlay 捕获滚动事件的问题，建议升级到最新发布版本。

## 4. 运维建议

- 将 `compose.pgsql.yaml` 与数据卷分离托管，使用只读反向代理对外暴露 `/api/Repository/RepositoryList` 等接口。
- 启用 v2.0.1 引入的 Channel 化消息处理后，注意为 `Channel` 消费者配置 `MaxRetryAttempts`（v2.0.1 #315），避免单条任务拖垮队列。
- 对接自托管 Git 平台时，可参考社区提案 #371（Forgejo、MCP auth、OAuth、i18n）准备前置能力。
- 升级到 v2.0.3 后，可使用新增的 MCP Server（OAuth 2.1）与 Slack 消息通道作为运维通知出口。

资料来源：[Makefile:1-60]()、资料来源：[compose.pgsql.yaml:1-40]()、资料来源：[.env.example:1-80]()

```mermaid
flowchart LR
  A[Git/Zip 导入] --> B[任务队列<br/>Channel]
  B --> C[WikiGenerator]
  C --> D[LLM 端点<br/>CHAT/ANALYSIS]
  C --> E[(DB<br/>SQLite/Postgres)]
  C --> F[/repositories 目录]
  D -- bad response --> G[网关/SDK 异常]
  C -- 工具调用失控 --> H[限流与重试]
  E --> I[管理后台]
  F --> I
  I --> J[Wiki 前端<br/>导出/浏览]

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：AIDotNet/OpenDeepWiki

摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：配置坑 - 来源证据：Please add support for the Vietnamese language.。

## 1. 配置坑 · 来源证据：Please add support for the Vietnamese language.

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Please add support for the Vietnamese language.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/370 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 能力坑 · 能力证据存在缺口

- 严重度：high
- 证据强度：source_linked
- 发现：Sandbox install result is missing.
- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
- 证据：evidence.evidence_gaps | https://github.com/AIDotNet/OpenDeepWiki | Sandbox install result is missing.

## 3. 运行坑 · 沙箱验证已有失败原因

- 严重度：high
- 证据强度：runtime_trace
- 发现：llm_blocked_sandbox_execution
- 对用户的影响：失败原因未处理前，不应向用户暗示项目可顺利运行。
- 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
- 证据：sandbox_validation_results | planner_decision=llm_blocked; planner_reason=docker compose up -d is not in the deterministic allowlist and is not a single-package pip/npm/npx/uvx install, so it cannot be selected under the isolated_install policy.; failure=llm_blocked_sandbox_execution

## 4. 安全/权限坑 · 来源证据：[Proposal] Upstream generic features from a self-hosted fork (Forgejo, MCP auth, i18n, OAuth…) / 回馈通用功能提案

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Proposal] Upstream generic features from a self-hosted fork (Forgejo, MCP auth, i18n, OAuth…) / 回馈通用功能提案
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/371 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 安装坑 · 依赖 Docker 环境

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker compose up -d
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker compose up -d`
- 证据：identity.distribution | https://github.com/AIDotNet/OpenDeepWiki | docker compose up -d

## 6. 安装坑 · 安装命令尚未沙箱验证

- 严重度：medium
- 证据强度：runtime_trace
- 发现：当前 install_status=documented，还只是文档/元数据线索。
- 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
- 复现命令：`docker compose up -d`
- 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
- 证据：downstream_validation.install_status | https://github.com/AIDotNet/OpenDeepWiki | install_status=documented; command=docker compose up -d

## 7. 安装坑 · 来源证据：【bug】如果导入了一个分支，则无法再次导入其他分支代码

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：【bug】如果导入了一个分支，则无法再次导入其他分支代码
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/353 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 8. 配置坑 · 来源证据：bad_response_status_code 最新代码调用本地llm模型api报错 Can only get item pairs from a mapping

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bad_response_status_code 最新代码调用本地llm模型api报错 Can only get item pairs from a mapping
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/307 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/AIDotNet/OpenDeepWiki | README/documentation is current enough for a first validation pass.

## 10. 运行坑 · Quick Start 尚未实际跑通

- 严重度：medium
- 证据强度：runtime_trace
- 发现：quickstart_status=not_attempted。
- 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
- 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
- 证据：downstream_validation.quickstart_status | https://github.com/AIDotNet/OpenDeepWiki | quickstart_status=not_attempted; sandbox_quickstart_status=blocked

## 11. 维护坑 · 来源证据：【bug】wiki界面点击导出压缩包按钮，生成的压缩包无法打开

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：【bug】wiki界面点击导出压缩包按钮，生成的压缩包无法打开
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/355 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 12. 维护坑 · 来源证据：【bug】有子标题的目录，点击后文档显示不存在

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：【bug】有子标题的目录，点击后文档显示不存在
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/354 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 13. 维护坑 · 来源证据：【ux】目录滚动困难

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：【ux】目录滚动困难
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/356 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 14. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/AIDotNet/OpenDeepWiki | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/AIDotNet/OpenDeepWiki | no_demo; severity=medium

## 16. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 证据：risks.safety_notes | https://github.com/AIDotNet/OpenDeepWiki | No sandbox install has been executed yet; downstream must verify before user use.

## 17. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/AIDotNet/OpenDeepWiki | no_demo; severity=medium

## 18. 安全/权限坑 · 来源证据：WikiGenerator.ExecuteAgentWithRetryAsync has no max-tool-call guard — a stuck-loop model burns MaxRetryAttempts × (Time…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：WikiGenerator.ExecuteAgentWithRetryAsync has no max-tool-call guard — a stuck-loop model burns MaxRetryAttempts × (TimeoutSeconds / per-call) paid LLM calls pe…
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/374 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 19. 安全/权限坑 · 来源证据：生成的文档未保存到数据库

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：生成的文档未保存到数据库
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/279 | 来源类型 github_issue 暴露的待验证使用条件。

## 20. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/AIDotNet/OpenDeepWiki | issue_or_pr_quality=unknown

## 21. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/AIDotNet/OpenDeepWiki | release_recency=unknown

<!-- canonical_name: AIDotNet/OpenDeepWiki; human_manual_source: deepwiki_human_wiki -->