企业官网建设流程全解析

DeepWiki-Open 源码本地构建与运行指南：为任意仓库一键生成 Wiki

【免费下载链接】deepwiki-openOpen Source DeepWiki: AI-Powered Wiki Generator for GitHub/Gitlab/Bitbucket Repositories. Join the discord: https://discord.gg/gMwThUMeme项目地址: https://gitcode.com/gh_mirrors/de/deepwiki-open

DeepWiki-Open 用 AI 给 GitHub、GitLab、Bitbucket 仓库自动生成可交互的文档 Wiki：解析代码结构、写出 Markdown 文档、画出 Mermaid 图表，还能对代码库提问。按本教程完成源码本地构建后，你会得到一套自己可控的完整环境——FastAPI 后端监听 8001 端口，Next.js 前端跑在 3000 端口，输入一个仓库 URL 就能生成带目录导航的文档站点。

项目速览

输入仓库地址后，它会克隆并分析仓库、为代码建立向量索引（FAISS），再由你选定的 LLM 生成文档与图表。除生成 Wiki 外，还有基于 RAG 的仓库问答和最多 5 轮迭代的深度研究模式，私有仓库可以用个人访问令牌（PAT）授权访问。所有数据都存在本机，不依赖云服务。

动手前先核对这张清单

硬件上，4 核 CPU、8GB 内存、10GB 可用磁盘是基本线；如果你打算用 Ollama 跑本地模型，建议 16GB 内存并预留模型下载空间。网络方面，克隆代码需要能访问目标仓库，使用云端模型时需要能访问 Google、OpenAI 或 OpenRouter 的 API 端点。软件版本按仓库构建文件核对：

克隆源码并配好 .env

把仓库克隆到本地

git clone https://gitcode.com/gh_mirrors/de/deepwiki-open cd deepwiki-open

逐项填好环境变量

在项目根目录创建.env文件，逐项含义如下：

示例文件：

# 在项目根目录创建 .env echo "OPENAI_API_KEY=YOUR_OPENAI_API_KEY" > .env echo "GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY" >> .env # 可选：OpenRouter # echo "OPENROUTER_API_KEY=YOUR_OPENROUTER_API_KEY" >> .env # 可选：非本机 Ollama # echo "OLLAMA_HOST=http://192.168.1.100:11434" >> .env

密钥申请入口：Google 密钥在 Google AI Studio 获取，OpenAI 密钥在 OpenAI Platform 控制台获取，OpenRouter 密钥在 OpenRouter 官网获取。

构建与启动：容器化最快，手动最灵活

两条路径按场景选：容器化一条命令同时拉起前后端，环境完全隔离，适合验证功能和日常使用；手动构建前后端各占一个终端，方便改代码调试，适合二次开发。

路径 A：Docker Compose 一条命令起服务

# 构建镜像并启动（首次会编译前端、装 Python 依赖，耐心等待） docker compose up -d --build

docker-compose.yml 映射了 3000（前端）和 8001（API）两个端口，并通过env_file读取你刚建的.env。两个细节值得知道：宿主机~/.adalflow目录被挂载进容器，克隆的仓库、FAISS 索引和 Wiki 缓存都存在里面，容器删了数据也不丢；mem_limit: 6g限制了容器内存上限。构建完成后打开浏览器访问http://localhost:3000即可。

路径 B：手动装依赖、分前后端启动

后端依赖用 Poetry 管理（依赖清单在 api/pyproject.toml，没有 requirements.txt），在仓库根目录执行：

# 安装 Python 依赖，虚拟环境创建在 api/.venv python -m pip install poetry==2.0.1 poetry install -C api

前端依赖在根目录的 package.json（Next.js 15、React 19）：

# 安装前端依赖，npm 或 yarn 均可 npm install

之后开两个终端，分别在仓库根目录启动：

# 终端 1：启动后端 API（默认 8001 端口） python -m api.main # 终端 2：启动前端开发服务器（3000 端口） npm run dev

前端通过 next.config.ts 里的SERVER_BASE_URL环境变量找到后端地址，未设置时默认就是http://localhost:8001，一般不用改。

读懂这套前后端分离的结构

deepwiki-open/ ├── api/ # FastAPI 后端 │ ├── main.py # 入口：加载 .env、装配 CORS 与全部路由、uvicorn 启动 │ ├── config.py # 读取 JSON 配置与环境变量，构建 LLM/嵌入客户端 │ ├── repository.py # 克隆并读取仓库文件 │ ├── routers/ # 路由层 │ │ ├── wiki.py # Wiki 生成与缓存 │ │ ├── chat.py # RAG 仓库问答（流式） │ │ ├── codemap.py # 代码地图 │ │ └── system.py # /health 健康检查、模型配置下发 │ ├── services/wiki/ # Wiki 生成的结构规划与内容填充 │ ├── rag/ # 向量索引与检索（FAISS） │ ├── clients/ # 各家模型客户端：google/openai/ollama 等 │ ├── config/ │ │ ├── generator.json # 可用生成模型清单，默认 gemini-2.5-flash │ │ ├── embedder.json # 嵌入模型与文本分块参数 │ │ └── repo.json # 文件过滤与 50GB 仓库大小上限 │ └── logs/application.log # 后端日志（自动生成） ├── src/ # Next.js 15 前端 │ ├── app/ │ │ ├── page.tsx # 落地页：输入仓库 URL │ │ ├── [owner]/[repo]/ # 生成后的 Wiki 页面、slides、workshop │ │ └── api/ # 代理层，把请求转发到后端 8001 │ ├── components/ # Ask 问答、WikiTreeView、Mermaid 渲染等 │ ├── messages/ # 多语言文案（含 zh.json） │ └── utils/ # 仓库准备、任务轮询、WebSocket 封装 ├── package.json # 前端依赖清单 ├── docker-compose.yml # 容器编排 └── .env # 环境变量（需你手动创建）

职责一句话概括：routers/只负责接收请求，真正干活的是services/wiki/（先规划 Wiki 结构、再逐页填内容）和rag/（建索引、做检索）；src/app/api/ 是前端的反向代理层，浏览器请求统一打到 3000 端口再被转发给 8001 的 FastAPI。

验证服务真的跑起来了

后端健康检查来自 api/routers/system.py：

curl http://localhost:8001/health # 期望返回 # {"status":"healthy","timestamp":"...","service":"deepwiki-api"}

再访问http://localhost:8001/，会返回按模块分组的端点清单，确认各路由已注册。

前端验证按这个流程走：打开http://localhost:3000，输入一个仓库 URL（比如github.com/openai/codex），点 Generate Wiki。成功标志是页面开始流式输出文档，随后出现左侧目录树、正文 Markdown、代码高亮和 Mermaid 图；在 Ask 面板提问仓库问题，回答会实时流式返回。生成过的仓库会被缓存（api/routers/wiki.py 管理），再次访问同一仓库直接命中缓存，不会重新生成。

进阶配置：换模型、本地推理、私有仓库

换模型。前端模型选择器的内容来自/models/config接口，数据源是 api/config/generator.json，目前内置 google、openai、openrouter、ollama、bedrock、azure、dashscope 等 provider，每个 provider 都有default_model和可选模型清单，supportsCustomModel: true允许在前端手输自定义模型标识。改 JSON 即可增删模型，不动代码。配置文件目录可用DEEPWIKI_CONFIG_DIR环境变量指到别处。

Ollama 本地推理。完全离线、不花 API 费用，但生成速度依赖本机性能：

# 1. 拉取嵌入模型和生成模型 ollama pull nomic-embed-text ollama pull qwen3:1.7b

然后.env中设置DEEPWIKI_EMBEDDER_TYPE=ollama，并用仓库自带的模板替换嵌入配置：

cp api/config/embedder.ollama.json.bak api/config/embedder.json

启动后在界面勾选 "Use Local Ollama" 选项再生成。详见 Ollama-instruction.md。

私有仓库与访问控制。输入私有仓库时，点界面上的 "+ 添加访问令牌"，填入 GitHub 或 GitLab 的个人访问令牌即可授权克隆。如果要和别人共享这套部署，可以启用授权模式限制 Wiki 生成：

DEEPWIKI_AUTH_MODE=true DEEPWIKI_AUTH_CODE=YOUR_SECRET_CODE

启用后前端会要求输入授权码才能触发生成。

常见问题：现象 → 原因 → 解决

• 现象：后端启动即报 "缺少环境变量"。原因：.env不在仓库根目录，或密钥项缺失。解决：确认文件位置，补齐OPENAI_API_KEY/GOOGLE_API_KEY后重启。
• 现象：3000 或 8001 端口被占用，服务起不来。原因：端口冲突。解决：.env中设PORT=8002（前端npm run dev可换--port参数），两处保持一致。
• 现象：选 Ollama 模型后提示 "Cannot connect to Ollama server"。原因：Ollama 没在跑，或地址端口不对。解决：ollama list验证进程，确认OLLAMA_HOST与 11434 端口配置。
• 现象：生成中途报 "生成 Wiki 时出错"。原因：仓库太大或模型额度不足。解决：先换小仓库试，api/config/repo.json 里仓库上限是 50GB，超大仓库建议换云端大模型 provider。
• 现象：改了代码但后端没生效。原因：手动模式下后端以开发模式运行（NODE_ENV非 production 时 uvicorn 开启 reload），但 reload 只监视api/目录。解决：直接 Ctrl+C 重启python -m api.main。

排查时先看后端日志，默认落在api/logs/application.log，可用LOG_FILE_PATH改路径、LOG_LEVEL=DEBUG打开调试级别；再看浏览器控制台的 JS 报错。多数问题重启两个服务就能恢复。

写在最后

到这里，一个属于你自己的 Wiki 生成器已经在http://localhost:3000跑起来了。把任何仓库 URL 丢给它，剩下的事交给模型。

【免费下载链接】deepwiki-openOpen Source DeepWiki: AI-Powered Wiki Generator for GitHub/Gitlab/Bitbucket Repositories. Join the discord: https://discord.gg/gMwThUMeme项目地址: https://gitcode.com/gh_mirrors/de/deepwiki-open