DeepWiki-Open 从零开始本地部署指南

需求分析：为什么选择本地部署

在开始部署之前，让我们先了解为什么需要本地部署DeepWiki-Open。这款AI驱动的Wiki生成工具能够为GitHub、GitLab或BitBucket仓库自动创建交互式文档。本地部署意味着您可以完全掌控数据隐私、自定义配置，并且不受外部服务可用性限制。特别适合需要处理私有仓库或对数据安全有严格要求的团队。

DeepWiki-Open的核心价值在于它能分析代码结构、生成全面文档、创建可视化图表并组织成易于导航的Wiki系统，这一切都可以在您自己的服务器环境中完成。

准备工作：环境检查与依赖安装

系统兼容性检查清单

在开始部署前，请确保您的系统满足以下要求：

检查项	最低要求	推荐配置
CPU	4核	8核及以上
内存	8GB	16GB
硬盘空间	10GB可用空间	20GB SSD
操作系统	Linux/macOS/Windows	Ubuntu 20.04 LTS或更高版本
网络	能访问Git仓库	稳定的互联网连接

必备软件安装

DeepWiki-Open需要以下软件支持，请确保它们已正确安装：

# 检查Python版本 (需要3.8及以上)
python --version

# 检查Node.js版本 (需要18及以上)
node --version

# 检查npm或yarn
npm --version
# 或
yarn --version

# 检查Git
git --version

# 检查Docker和Docker Compose (可选)
docker --version
docker-compose --version

💡 如果缺少任何依赖，请根据您的操作系统安装相应软件。对于Ubuntu系统，可以使用以下命令安装基础依赖：

sudo apt update && sudo apt install -y python3 python3-pip nodejs npm git

实施步骤：从源码到运行

1. 获取项目源码

首先，克隆DeepWiki-Open项目仓库到本地：

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

验证方法

克隆完成后，检查项目目录是否包含以下关键文件夹：

• api/ - 后端API服务
• src/ - 前端Web应用
• screenshots/ - 项目截图资源

2. 配置环境变量

创建并配置必要的环境变量文件：

# 在项目根目录创建.env文件
touch .env

# 使用文本编辑器打开.env文件
nano .env

在.env文件中添加以下配置（根据您的需求选择或修改）：

# API密钥配置
GOOGLE_API_KEY=your_google_api_key
OPENAI_API_KEY=your_openai_api_key
OPENROUTER_API_KEY=your_openrouter_api_key

# 嵌入模型配置
DEEPWIKI_EMBEDDER_TYPE=google  # 可选值: google, openai, ollama

# Ollama配置 (当使用本地Ollama模型时)
OLLAMA_HOST=http://localhost:11434

# 日志配置
LOG_LEVEL=INFO
LOG_FILE_PATH=./api/logs/application.log

环境变量说明

参数名称	说明	可选值	默认值
DEEPWIKI_EMBEDDER_TYPE	选择嵌入模型类型	google, openai, ollama	openai
OLLAMA_HOST	Ollama服务地址	有效的URL	http://localhost:11434
LOG_LEVEL	日志级别	DEBUG, INFO, WARNING, ERROR	INFO

验证方法

保存文件后，使用以下命令检查文件是否创建成功：

cat .env

3. 选择部署方式

DeepWiki-Open提供两种部署方式，您可以根据实际需求选择：

部署方式	优点	缺点	适用场景
Docker Compose	配置简单，环境隔离，一键启动	需要Docker环境，资源占用略高	快速部署，生产环境
手动部署	资源占用低，自定义程度高	配置步骤多，依赖管理复杂	开发环境，定制化部署

方式一：Docker Compose部署（推荐）

Docker Compose方式可以简化部署流程，避免环境依赖问题：

# 使用Docker Compose启动服务
docker-compose up -d

# 查看服务状态
docker-compose ps

方式二：手动部署

如果您选择手动部署，需要分别启动后端API和前端应用：

后端API服务

# 进入API目录
cd api

# 安装Python依赖
pip install -r requirements.txt

# 启动API服务器
python -m api.main

前端Web应用

# 返回项目根目录
cd ..

# 安装JavaScript依赖
npm install
# 或
yarn install

# 启动开发服务器
npm run dev
# 或
yarn dev

验证方法

部署完成后，通过以下方式验证服务是否正常运行：

• Web界面：打开浏览器访问 http://localhost:3000
• API服务：访问 http://localhost:8001/docs 查看API文档

成功启动后，您将看到DeepWiki的主界面：

深度配置：定制您的DeepWiki

模型选择与配置

DeepWiki支持多种AI模型提供商，您可以通过修改配置文件选择适合您的模型：

• 生成器配置：api/config/generator.json
• 嵌入模型配置：api/config/embedder.json

💡 提示：如果您没有API密钥，可以使用本地Ollama模型。需要先安装Ollama并下载相应模型，然后在.env文件中设置DEEPWIKI_EMBEDDER_TYPE=ollama。

底层工作机制

DeepWiki-Open的工作流程主要分为三个阶段：

1. 数据采集：从Git仓库拉取代码和文档
2. 处理与嵌入：通过AI模型分析代码结构并生成向量表示
3. 文档生成：基于分析结果创建结构化Wiki内容

私有仓库访问配置

如果需要处理私有仓库，您需要配置访问令牌：

1. 在DeepWiki界面点击"+ Add access tokens for private repositories"
2. 输入您的GitHub或GitLab个人访问令牌
3. 令牌仅存储在内存中，不会持久化保存

性能优化建议

为了获得更好的使用体验，您可以考虑以下优化措施：

资源分配优化

• 内存分配：确保系统至少有8GB可用内存，对于大型仓库建议16GB以上
• CPU核心：处理大型项目时，更多的CPU核心可以显著提升文档生成速度
• 磁盘I/O：使用SSD存储可以加快代码库克隆和文件处理速度

缓存策略

DeepWiki会缓存处理过的仓库数据，您可以通过以下方式管理缓存：

# 清理缓存（位于api/cache目录）
rm -rf api/cache/*

模型选择建议

根据不同场景选择合适的模型：

使用场景	推荐模型	优势
快速预览	本地Ollama模型	无需API密钥，完全本地运行
生产环境	OpenAI/Google模型	生成质量高，支持复杂分析
低成本方案	OpenRouter	提供多种模型选择，按使用付费

问题解决：常见故障排除

服务启动问题

问题症状	可能原因	解决方案
API服务启动失败	端口被占用	更改api/config.py中的端口配置
前端无法访问API	CORS配置问题	检查api/main.py中的CORS设置
Docker容器启动失败	资源不足	增加Docker资源分配或关闭其他容器

API密钥问题

如果遇到API密钥相关错误：

1. 确认.env文件中的密钥是否正确
2. 检查密钥是否具有足够的权限
3. 尝试创建新的API密钥并更新.env文件

开启调试日志

如需详细调试信息，可在.env文件中设置：

LOG_LEVEL=DEBUG
LOG_FILE_PATH=./debug.log

日志文件位于api/logs/application.log，可通过以下命令查看：

tail -f api/logs/application.log

总结

通过本指南，您已经了解如何从零开始在本地部署DeepWiki-Open。无论是使用Docker快速部署，还是手动配置进行二次开发，DeepWiki都提供了灵活的选项。现在您可以开始体验AI驱动的智能Wiki生成功能，为您的项目创建专业的文档。

DeepWiki-Open的强大之处在于它能够将复杂的代码库转化为易于理解的文档，帮助团队更快地掌握项目结构和使用方法。随着您对系统的熟悉，您可以进一步探索高级配置选项，定制适合您团队需求的Wiki生成流程。