feat(wiki): 支持集群级可配置并发生成并修复分布式抢锁

用数据库 slot 和实例心跳在多实例间正确分配同时生成配额，默认并发为 1。

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 239573049

compose.pgsql.yaml

@@ -59,6 +59,9 @@ services:
       # Wiki 生成并行数 (默认: 5)
       - WIKI_PARALLEL_COUNT=5
 
+      # 集群同时生成的仓库 Wiki 数量 (默认: 1，多实例共享这个上限)
+      - WIKI_MAX_CONCURRENT_GENERATIONS=1
+
       # 多语言支持 (逗号分隔，如: en,zh,ja,ko,es,fr,de,pt-br)
       - WIKI_LANGUAGES=en,zh,zh-tw,ja,ko,es,fr,de,pt-br,pl,ru,ar
     volumes:

compose.yaml

@@ -69,6 +69,9 @@
       # Wiki 生成并行数 (默认: 5)
       - WIKI_PARALLEL_COUNT=${WIKI_PARALLEL_COUNT:-5}
 
+      # 集群同时生成的仓库 Wiki 数量 (默认: 1，多实例共享这个上限)
+      - WIKI_MAX_CONCURRENT_GENERATIONS=${WIKI_MAX_CONCURRENT_GENERATIONS:-1}
+
       # 多语言支持 (逗号分隔，如: en,zh,ja,ko,es,fr,de,pt-br)
       - WIKI_LANGUAGES=${WIKI_LANGUAGES:-en,zh,zh-tw,ja,ko,es,fr,de,pt-br,pl,ru,ar}
     volumes:

docs/content/docs/configuration/environment-variables.mdx

@@ -17,8 +17,8 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 | 变量 | 必需 | 默认值 | 描述 |
 |---|---|---|---|
-| `DB_TYPE` | 否 | `sqlite` | 数据库后端类型。支持的值：`sqlite`、`postgresql` |
-| `CONNECTION_STRING` | 否 | `Data Source=/data/opendeepwiki.db` | 数据库连接字符串。格式取决于 `DB_TYPE` |
+| `DB_TYPE` | 否 | `sqlite` | 数据库后端类型。支持的值：`sqlite`、`postgresql`（等价于 `Database__Type`） |
+| `CONNECTION_STRING` | 否 | `Data Source=/data/opendeepwiki.db` | 数据库连接字符串（等价于 `ConnectionStrings__Default`） |
 
 对于 PostgreSQL，使用 Npgsql 连接字符串格式：
 
@@ -57,8 +57,10 @@ JWT 发行者、受众和过期时间通过 `appsettings.json` 的 `Jwt` 部分
 | 变量 | 必需 | 默认值 | 描述 |
 |---|---|---|---|
 | `CHAT_API_KEY` | 是 | — | 聊天 AI 服务的 API 密钥 |
-| `ENDPOINT` | 是 | `https://api.routin.ai/v1` | 聊天 AI 服务端点 URL |
-| `CHAT_REQUEST_TYPE` | 否 | `OpenAI` | AI 提供商类型：`OpenAI`、`AzureOpenAI`、`Anthropic`、`OpenAIResponses` |
+| `ENDPOINT` | 是 | `https://api.routin.ai/v1`（内置默认） | 聊天 AI 服务端点 URL |
+| `CHAT_REQUEST_TYPE` | 否 | `OpenAI` | AI 提供商类型：`OpenAI`、`AzureOpenAI`、`Anthropic`、`OpenAIResponses`、`DeepSeekOpenAI` |
+
+这些变量配置用于生成文档目录（目录）结构的 AI 模型。
 
 ## Wiki 生成 — 目录
 
@@ -69,7 +71,7 @@ JWT 发行者、受众和过期时间通过 `appsettings.json` 的 `Jwt` 部分
 | `WIKI_CATALOG_MODEL` | 否 | `gpt-4o` | 目录生成的模型名称 |
 | `WIKI_CATALOG_ENDPOINT` | 是 | — | 目录生成的 API 端点 |
 | `WIKI_CATALOG_API_KEY` | 是 | — | 目录生成的 API 密钥 |
-| `WIKI_CATALOG_REQUEST_TYPE` | 否 | `OpenAI` | 提供商类型：`OpenAI`、`AzureOpenAI`、`Anthropic`、`OpenAIResponses` |
+| `WIKI_CATALOG_REQUEST_TYPE` | 否 | `OpenAI` | 提供商类型：`OpenAI`、`AzureOpenAI`、`Anthropic`、`OpenAIResponses`、`DeepSeekOpenAI` |
 
 ## Wiki 生成 — 内容
 
@@ -80,7 +82,7 @@ JWT 发行者、受众和过期时间通过 `appsettings.json` 的 `Jwt` 部分
 | `WIKI_CONTENT_MODEL` | 否 | `gpt-4o` | 内容生成的模型名称 |
 | `WIKI_CONTENT_ENDPOINT` | 是 | — | 内容生成的 API 端点 |
 | `WIKI_CONTENT_API_KEY` | 是 | — | 内容生成的 API 密钥 |
-| `WIKI_CONTENT_REQUEST_TYPE` | 否 | `OpenAI` | 提供商类型：`OpenAI`、`AzureOpenAI`、`Anthropic`、`OpenAIResponses` |
+| `WIKI_CONTENT_REQUEST_TYPE` | 否 | `OpenAI` | 提供商类型：`OpenAI`、`AzureOpenAI`、`Anthropic`、`OpenAIResponses`、`DeepSeekOpenAI` |
 
 ## Wiki 生成 — 翻译（可选）
 
@@ -98,6 +100,7 @@ JWT 发行者、受众和过期时间通过 `appsettings.json` 的 `Jwt` 部分
 | 变量 | 必需 | 默认值 | 描述 |
 |---|---|---|---|
 | `WIKI_PARALLEL_COUNT` | 否 | `5` | 并行文档生成任务数。更高的值加快生成但使用更多资源 |
+| `WIKI_MAX_CONCURRENT_GENERATIONS` | 否 | `1` | 整个集群同时进行仓库 Wiki 生成的上限。多实例共享这个配额 |
 | `WIKI_LANGUAGES` | 否 | `en,zh,zh-tw,ja,ko,es,fr,de,pt-br,pl,ru,ar` | 多语言 wiki 生成的目标语言逗号分隔列表 |
 | `REPOSITORIES_DIRECTORY` | 否 | `/data` | 用于存储克隆仓库文件的目录 |
 | `WIKI_MAX_OUTPUT_TOKENS` | 否 | `32000` | 单次 AI 生成的最大输出 Token 数，防止回复过长 |
@@ -123,14 +126,36 @@ JWT 发行者、受众和过期时间通过 `appsettings.json` 的 `Jwt` 部分
 | `IncrementalUpdate:RetryBaseDelayMs` | `1000` | 重试之间的基础延迟（毫秒），使用指数退避 |
 | `IncrementalUpdate:ManualTriggerPriority` | `100` | 手动触发的更新任务的优先级值 |
 
+## 仓库导入与存储
+
+| 变量 | 必需 | 默认值 | 描述 |
+|---|---|---|---|
+| `REPOSITORIES_DIRECTORY` | 否 | `/data` | 用于存储克隆仓库文件的目录 |
+| `RepositoryAnalyzer__AllowedLocalPathRoots__0` | 否 | — | 允许导入的本地目录根路径白名单（本地目录导入功能必需） |
+| `RepositoryAnalyzer__LocalDirectoryImportMode` | 否 | `Copy` | 本地目录导入模式：`Copy`（复制）或 `Reference`（引用） |
+| `RepositoryAnalyzer__CleanupAfterProcessing` | 否 | `false` | 处理完成后是否清理工作区 |
+
 ## 功能标志
 
 | 变量 | 必需 | 默认值 | 描述 |
 |---|---|---|---|
+| `MCP_ENABLED` | 否 | `true` | 是否启用 MCP 端点 |
 | `MCP_STREAMABLE` | 否 | — | 为外部 AI 服务配置 MCP Streamable HTTP 端点。格式：`serviceName=url,serviceName2=url2` |
 
 详见 [MCP 协议](/docs/mcp)。
 
+## Graphify 图谱产物（可选）
+
+后端 Docker 镜像内置 `graphifyy` CLI。配置以下变量即可启用：
+
+| 变量 | 描述 |
+|---|---|
+| `GRAPHIFY_BACKEND` | Graphify 后端类型 |
+| `GRAPHIFY_MODEL` | Graphify 使用的模型 |
+| `GRAPHIFY_OUTPUT_ROOT` | 产物输出目录（Docker 中默认 `/data/graphify-artifacts`） |
+| `GRAPHIFY_OPENAI_BASE_URL` / `GRAPHIFY_OPENAI_API_KEY` | OpenAI 兼容凭证 |
+| `OPENAI_BASE_URL` / `OPENAI_API_KEY`、`OLLAMA_BASE_URL` / `OLLAMA_MODEL` 等 | 各提供商回退凭证 |
+
 ## ASP.NET Core 运行时
 
 | 变量 | 必需 | 默认值 | 描述 |
@@ -146,7 +171,8 @@ JWT 发行者、受众和过期时间通过 `appsettings.json` 的 `Jwt` 部分
 |---|---|---|---|
 | `NODE_ENV` | 否 | `production` | Node.js 环境模式 |
 | `API_PROXY_URL` | 是 | `http://localhost:5265` | 前端代理的后端 API URL。在 Docker 中，使用服务名称：`http://opendeepwiki:8080` |
-| `SITE_URL` | 否 | `http://localhost:3000` | 公开站点 URL，用于 sitemap、robots.txt、canonical URL 和社交分享元数据。生产环境应配置为实际访问域名 |
+| `SITE_URL` | 否 | `http://localhost:8090` | 公开站点 URL，用于 sitemap、robots.txt、canonical URL 和社交分享元数据。生产环境应配置为实际访问域名 |
+| `SITEMAP_REVALIDATE_SECONDS` | 否 | `3600` | sitemap 缓存 TTL（秒） |
 
 ## 示例：最小 `.env` 文件
 
@@ -175,5 +201,5 @@ WIKI_LANGUAGES=en,zh,zh-tw,ja,ko,es,fr,de,pt-br,pl,ru,ar
 ```
 
 <Callout type="info">
-  OpenDeepWiki 在启动时自动从项目根目录或应用目录加载 `.env` 文件。无需额外配置。
+  OpenDeepWiki 在启动时自动从当前目录或应用程序目录加载 `.env` 文件（`Program.cs` 中的 `LoadEnvFile`）。无需额外配置。
 </Callout>

docs/content/docs/deployment/docker-compose.mdx

@@ -7,16 +7,16 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 # Docker Compose 部署
 
-OpenDeepWiki 在项目根目录提供 `compose.yaml`，定义了两个服务：后端 API 和前端 web 应用。
+OpenDeepWiki 在项目根目录提供 `compose.yaml`，定义了两个服务：后端 API 和前端 web 应用。PostgreSQL 用户可直接使用 `compose.pgsql.yaml`。
 
 ## 服务架构
 
-| 服务 | 端口 | 描述 |
-|---|---|---|
-| `opendeepwiki` | `8080` | 带有 AI 处理的 ASP.NET Core 后端 API |
-| `web` | `3000` | Next.js 前端应用 |
+| 服务 | 容器端口 | 默认宿主机映射 | 描述 |
+|---|---|---|---|
+| `opendeepwiki` | `8080` | `8081:8080` | 带有 AI 处理的 ASP.NET Core 后端 API |
+| `web` | `3000` | `8090:3000` | Next.js 前端应用 |
 
-前端依赖于后端，并在其健康检查通过后才启动。
+> 端口映射以仓库中 `compose.yaml` 的实际内容为准，可按需修改。前端通过内部网络使用 `API_PROXY_URL=http://opendeepwiki:8080` 访问后端。
 
 ## 快速部署
 
@@ -27,13 +27,15 @@ cd OpenDeepWiki
 
 # 编辑 compose.yaml 中的环境变量（见下文）
 # 然后启动所有服务
-docker-compose up -d
+docker compose up -d
 ```
 
-在 `http://localhost:3000` 访问应用。
+在 `http://localhost:8090` 访问应用。
 
 ## 完整 compose.yaml 参考
 
+以下是当前 `compose.yaml` 的关键结构（完整内容以文件为准）：
+
 ```yaml
 services:
   opendeepwiki:
@@ -42,56 +44,57 @@ services:
       context: .
       dockerfile: src/OpenDeepWiki/Dockerfile
     ports:
-      - "8080:8080"
+      - "8081:8080"
     restart: unless-stopped
-    healthcheck:
-      test: ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 15s
     environment:
       - ASPNETCORE_ENVIRONMENT=Production
       - URLS=http://+:8080
 
       # 数据库
-      - DB_TYPE=sqlite
-      - CONNECTION_STRING=Data Source=/data/opendeepwiki.db
+      - Database__Type=${DB_TYPE:-sqlite}
+      - ConnectionStrings__Default=${CONNECTION_STRING:-Data Source=/data/opendeepwiki.db}
 
       # JWT
-      - JWT_SECRET_KEY=your-secret-key-change-in-production
+      - JWT_SECRET_KEY=${JWT_SECRET_KEY:-OpenDeepWiki-Default-Secret-Key-Please-Change-In-Production-Environment-2024}
 
-      # 仓库存储
+      # 仓库存储与本地目录导入白名单
       - REPOSITORIES_DIRECTORY=/data
+      - RepositoryAnalyzer__AllowedLocalPathRoots__0=${LOCAL_IMPORT_ROOT:-/host/home/youruser}
 
       # AI 服务（聊天）
-      - CHAT_API_KEY=your-api-key
-      - ENDPOINT=https://api.openai.com/v1
-      - CHAT_REQUEST_TYPE=OpenAI
+      - CHAT_API_KEY=${CHAT_API_KEY:-your-chat-api-key}
+      - ENDPOINT=${ENDPOINT:-https://api.openai.com/v1}
+      - CHAT_REQUEST_TYPE=${CHAT_REQUEST_TYPE:-OpenAI}
 
       # Wiki 目录生成
-      - WIKI_CATALOG_MODEL=gpt-4o
-      - WIKI_CATALOG_ENDPOINT=https://api.openai.com/v1
-      - WIKI_CATALOG_API_KEY=your-api-key
-      - WIKI_CATALOG_REQUEST_TYPE=OpenAI
+      - WIKI_CATALOG_MODEL=${WIKI_CATALOG_MODEL:-gpt-4o}
+      - WIKI_CATALOG_ENDPOINT=${WIKI_CATALOG_ENDPOINT:-https://api.openai.com/v1}
+      - WIKI_CATALOG_API_KEY=${WIKI_CATALOG_API_KEY:-your-catalog-api-key}
+      - WIKI_CATALOG_REQUEST_TYPE=${WIKI_CATALOG_REQUEST_TYPE:-OpenAI}
 
       # Wiki 内容生成
-      - WIKI_CONTENT_MODEL=gpt-4o
-      - WIKI_CONTENT_ENDPOINT=https://api.openai.com/v1
-      - WIKI_CONTENT_API_KEY=your-api-key
-      - WIKI_CONTENT_REQUEST_TYPE=OpenAI
+      - WIKI_CONTENT_MODEL=${WIKI_CONTENT_MODEL:-gpt-4o}
+      - WIKI_CONTENT_ENDPOINT=${WIKI_CONTENT_ENDPOINT:-https://api.openai.com/v1}
+      - WIKI_CONTENT_API_KEY=${WIKI_CONTENT_API_KEY:-your-content-api-key}
+      - WIKI_CONTENT_REQUEST_TYPE=${WIKI_CONTENT_REQUEST_TYPE:-OpenAI}
 
       # Wiki 翻译（可选，回退到内容配置）
       # - WIKI_TRANSLATION_MODEL=gpt-4o
       # - WIKI_TRANSLATION_ENDPOINT=https://api.openai.com/v1
       # - WIKI_TRANSLATION_API_KEY=your-api-key
       # - WIKI_TRANSLATION_REQUEST_TYPE=OpenAI
 
-      # 并行生成数量
-      - WIKI_PARALLEL_COUNT=5
-
-      # 多语言支持（逗号分隔）
-      - WIKI_LANGUAGES=en,zh,zh-tw,ja,ko,es,fr,de,pt-br,pl,ru,ar
+      # 并行生成数量 / 多语言支持
+      - WIKI_PARALLEL_COUNT=${WIKI_PARALLEL_COUNT:-5}
+      - WIKI_MAX_CONCURRENT_GENERATIONS=${WIKI_MAX_CONCURRENT_GENERATIONS:-1}
+      - WIKI_LANGUAGES=${WIKI_LANGUAGES:-en,zh,zh-tw,ja,ko,es,fr,de,pt-br,pl,ru,ar}
+
+      # Graphify 图谱产物（可选）
+      - GRAPHIFY_BACKEND=${GRAPHIFY_BACKEND:-}
+      - GRAPHIFY_MODEL=${GRAPHIFY_MODEL:-}
+      - GRAPHIFY_OUTPUT_ROOT=/data/graphify-artifacts
+      - GRAPHIFY_OPENAI_BASE_URL=${GRAPHIFY_OPENAI_BASE_URL:-}
+      - GRAPHIFY_OPENAI_API_KEY=${GRAPHIFY_OPENAI_API_KEY:-}
     volumes:
       - ./data:/data
 
@@ -101,23 +104,25 @@ services:
       context: ./web
       dockerfile: Dockerfile
     ports:
-      - "3000:3000"
+      - "8090:3000"
     restart: unless-stopped
-    depends_on:
-      opendeepwiki:
-        condition: service_healthy
     environment:
       - NODE_ENV=production
-      - SITE_URL=${SITE_URL:-http://localhost:3000}
+      - SITE_URL=${SITE_URL:-http://localhost:8090}
       - API_PROXY_URL=http://opendeepwiki:8080
 ```
 
+<Callout type="info">
+  根目录提供 `.env.example`，可复制为 `.env` 后通过 `${VAR:-default}` 插值注入配置，无需直接修改 `compose.yaml`。
+</Callout>
+
 ## 环境变量
 
 ### 必需变量
 
 | 变量 | 描述 | 示例 |
 |---|---|---|
+| `JWT_SECRET_KEY` | JWT 签名密钥（生产环境必须更改） | 长随机字符串 |
 | `CHAT_API_KEY` | 聊天 AI 服务的 API 密钥 | `sk-...` |
 | `ENDPOINT` | 聊天 AI 服务端点 | `https://api.openai.com/v1` |
 | `WIKI_CATALOG_API_KEY` | 目录生成的 API 密钥 | `sk-...` |
@@ -131,13 +136,17 @@ services:
 |---|---|---|
 | `DB_TYPE` | `sqlite` | 数据库类型：`sqlite` 或 `postgresql` |
 | `CONNECTION_STRING` | `Data Source=/data/opendeepwiki.db` | 数据库连接字符串 |
-| `JWT_SECRET_KEY` | 内置默认值 | JWT 签名密钥（生产环境需更改） |
 | `WIKI_CATALOG_MODEL` | `gpt-4o` | 目录生成模型 |
 | `WIKI_CONTENT_MODEL` | `gpt-4o` | 内容生成模型 |
-| `CHAT_REQUEST_TYPE` | `OpenAI` | AI 提供商类型 |
+| `CHAT_REQUEST_TYPE` | `OpenAI` | AI 提供商类型：`OpenAI`、`AzureOpenAI`、`OpenAIResponses`、`Anthropic`、`DeepSeekOpenAI` |
 | `WIKI_PARALLEL_COUNT` | `5` | 并行 wiki 生成任务数 |
+| `WIKI_MAX_CONCURRENT_GENERATIONS` | `1` | 集群同时生成的仓库 Wiki 数量，多实例共享 |
 | `WIKI_LANGUAGES` | `en,zh,zh-tw,ja,ko,es,fr,de,pt-br,pl,ru,ar` | 支持的语言（逗号分隔） |
-| `SITE_URL` | `http://localhost:3000` | 公开站点 URL，用于 sitemap、robots.txt、canonical URL 和社交分享元数据 |
+| `SITE_URL` | `http://localhost:8090` | 公开站点 URL，用于 sitemap、robots.txt、canonical URL 和社交分享元数据 |
+| `SITEMAP_REVALIDATE_SECONDS` | `3600` | sitemap 缓存 TTL（秒） |
+| `LOCAL_IMPORT_ROOT` | — | 允许导入的本地目录根路径（本地目录导入白名单） |
+| `MCP_ENABLED` | `true` | 是否启用 MCP 端点 |
+| `GRAPHIFY_*` 系列 | — | Graphify 图谱产物配置（Backend、Model、OpenAI 凭证等） |
 
 <Callout type="warn">
   在生产环境中始终更改 `JWT_SECRET_KEY`。默认密钥仅用于开发。
@@ -163,7 +172,7 @@ volumes:
 
 ## 健康检查
 
-后端包含内置的健康检查端点：
+后端内置健康检查端点 `/health`。`compose.pgsql.yaml` 中配置了健康检查与依赖顺序：
 
 ```yaml
 healthcheck:
@@ -174,48 +183,40 @@ healthcheck:
   start_period: 15s
 ```
 
-前端在此健康检查通过后才启动，确保 API 已准备好接受请求。
+PostgreSQL 编排中，后端在数据库 `service_healthy` 后才启动。SQLite 默认编排未启用 `depends_on` 条件，前端启动失败时检查后端是否就绪即可。
 
 ## 构建镜像
 
 ```bash
 # 构建所有镜像
-docker-compose build
+docker compose build
 
-# 为特定架构构建
-docker-compose build --build-arg ARCH=arm64   # Apple Silicon、AWS Graviton
-docker-compose build --build-arg ARCH=amd64   # Intel/AMD x86_64
+# 为特定架构构建（通过 Makefile）
+make build-arm   # ARM64：Apple Silicon、AWS Graviton
+make build-amd   # AMD64：Intel/AMD x86_64
 
 # 构建单个服务
-docker-compose build opendeepwiki   # 仅后端
-docker-compose build web            # 仅前端
-```
-
-如果已安装 `make`：
-
-```bash
-make build          # 构建全部
-make build-arm      # ARM 架构
-make build-amd      # AMD 架构
+docker compose build opendeepwiki   # 仅后端
+docker compose build web            # 仅前端
 ```
 
 ## 常见操作
 
 ```bash
 # 后台启动
-docker-compose up -d
+docker compose up -d
 
 # 查看日志
-docker-compose logs -f
+docker compose logs -f
 
 # 查看特定服务的日志
-docker-compose logs -f opendeepwiki
+docker compose logs -f opendeepwiki
 
 # 重启服务
-docker-compose restart
+docker compose restart
 
 # 停止服务
-docker-compose down
+docker compose down
 ```
 
 ## 一键部署
@@ -232,14 +233,14 @@ docker-compose down
 
 - 验证 AI API 密钥有效且端点可达
 - 检查 `CONNECTION_STRING` 与你的数据库类型匹配
-- 查看日志：`docker-compose logs opendeepwiki`
+- 查看日志：`docker compose logs opendeepwiki`
 
 ### 前端显示连接错误
 
-- 确保后端健康检查通过：`docker-compose ps`
+- 确保后端已启动：`docker compose ps`
 - `API_PROXY_URL` 必须指向后端容器：`http://opendeepwiki:8080`
 
 ### 磁盘空间不足
 
 - 克隆的仓库存储在 `./data` 中。通过 web UI 或 API 清理旧仓库
-- 对于大型部署，考虑从 SQLite 切换到 [PostgreSQL](/docs/deployment/database)
+- 对于大型部署，考虑从 SQLite 切换到 [PostgreSQL](/docs/deployment/database)（可直接使用 `compose.pgsql.yaml`）