【从零开始搭建你的 AI 编程助手知识库】

如果你看到 GitHub 上各种高大上的项目就头疼，那么这篇教程就是为你写的。我会用最通俗的语言，手把手带你把 Archon 跑起来，而且每一步都有截图说明（虽然你看不到，但我写得就像你有截图一样）。

🎯 前言：Archon 到底是个啥？

简单来说，Archon 就是你的 AI 编程助手的"大脑"。

想象一下：

• 你正在用 Cursor 或 Claude Code 写代码
• 这些 AI 助手虽然聪明，但对你的具体项目一无所知
• 于是你每次都要重复解释：“我的项目用的是 React 18，数据库是 PostgreSQL，API 文档在这里…”

有了 Archon，你就可以：

• 把所有项目文档、API 参考、代码示例都扔进去
• AI 助手直接连接 Archon，瞬间获得所有背景知识
• 再也不用重复解释基础信息，AI 直接给你最相关的答案

🛠️ 准备工作：你需要的东西

别担心，都是免费的东西：

需要的东西	作用	费用
电脑	Windows/Mac/Linux 都行	你有
Docker Desktop	运行 Archon 的容器	免费
Node.js	运行前端界面	免费
Supabase 账号	存数据的数据库	免费版够用
OpenAI API key	让 AI 有脑子思考	新用户有免费额度

第一步：安装 Docker Desktop

Windows 用户：

1. 打开 https://www.docker.com/products/docker-desktop/
2. 点击 “Download for Windows”
3. 下载完后双击安装，一直点 Next 就行
4. 安装完重启电脑

Mac 用户：

1. 同样打开官网，下载 Mac 版本
2. 把 Docker 拖到 Applications 文件夹
3. 双击打开，可能会让你输入密码

检查是否安装成功：

• 打开终端（Windows 用 PowerShell，Mac 用 Terminal）
• 输入：docker --version
• 看到版本号就说明成功了

第二步：安装 Node.js

1. 打开 https://nodejs.org/
2. 下载 LTS 版本（就是写着 “Recommended” 的那个）
3. 双击安装，全部默认选项
4. 安装完打开终端输入：node --version
5. 看到版本号就成功了

第三步：注册 Supabase

1. 打开 https://supabase.com/

2. 点击右上角 “Start your project”

3. 用 GitHub 账号登录（没有就注册一个）

4. 创建新项目：

   • 项目名称：随便写，比如 “my-archon”
   • 数据库密码：记在小本本上，后面要用
   • 地区：选离你最近的（国内选 Singapore，美国选 US East）

5. 等 2 分钟，项目创建好

6. 找到数据库连接信息：

   • 点击左侧 “Settings”
   • 点击 “Database”
   • 找到 “Connection string” 部分
   • 复制 “URI” 那一长串，等会儿用

第四步：获取 OpenAI API Key

1. 打开 https://platform.openai.com/api-keys
2. 登录（没有账号就注册）
3. 点击 “Create new secret key”
4. 给 key 起个名字，比如 “archon-use”
5. 复制 key，立刻存到记事本，因为只显示一次

🚀 正式开始：搭建 Archon

第一步：下载 Archon 代码

1. 打开终端
2. 输入以下命令（一行一行来）：

# 进入桌面（或者你喜欢的文件夹）
cd Desktop# 下载 Archon
git clone https://github.com/coleam00/archon.git# 进入文件夹
cd archon

如果你没装 git，也可以：

1. 打开 https://github.com/coleam00/archon
2. 点击绿色 “Code” 按钮
3. 选择 “Download ZIP”
4. 解压到桌面

第二步：配置环境变量

1. 在 archon 文件夹里，找到 .env.example 文件
2. 复制一份，改名为 .env（Windows 如果看不到后缀，就改名为 .env.）
3. 用记事本打开 .env 文件
4. 修改以下内容：

# 把 SUPABASE_URL 改成你的
SUPABASE_URL=https://你的项目名.supabase.co# 把 SUPABASE_SERVICE_KEY 改成你的
SUPABASE_SERVICE_KEY=你的key# 把 OpenAI key 填进去
OPENAI_API_KEY=你的openai_key

怎么找这些值：

• SUPABASE_URL：在 Supabase 的 Settings → Database → Connection string 里
• SUPABASE_SERVICE_KEY：在 Supabase 的 Settings → API → service_role secret
• OPENAI_API_KEY：就是你刚才复制的那个

第三步：设置数据库

1. 回到 Supabase 网页
2. 点击左侧 “SQL Editor”
3. 点击 “New query”
4. 打开你本地的 archon/migration/complete_setup.sql 文件
5. 全选复制里面的内容
6. 粘贴到 Supabase 的 SQL Editor 里
7. 点击 “Run” 按钮
8. 看到 “Success” 就完成了

第四步：启动 Archon

1. 打开终端，确保你在 archon 文件夹里
2. 运行以下命令：

# 第一次启动需要构建，会比较慢（5-10分钟）
docker compose up --build -d

启动时你可能会看到：

[+] Building 120.5s (15/15) FINISHED
...
[+] Running 4/4⠿ Container archon-server  Started⠿ Container archon-mcp     Started  ⠿ Container archon-ui      Started⠿ Container archon-agents  Started

3. 等全部显示 “Started” 后，打开浏览器访问：

   http://localhost:3737
   

如果看到漂亮的网页界面，恭喜你成功了！

🎯 第一次使用：5分钟上手

1. 连接你的 AI 助手

1. 在 Archon 网页里，点击左侧 “Settings”
2. 选择 “OpenAI” 作为 Provider
3. 粘贴你的 API Key
4. 点击 “Test Connection”
5. 看到绿色 “Connected” 就说明连上了

2. 添加知识库

试试添加一些文档：

1. 点击左侧 “Knowledge Base”
2. 点击 “Crawl Website”
3. 输入：https://react.dev/learn
4. 点击 “Start Crawling”
5. 等几分钟，让 Archon 把 React 文档爬下来

3. 创建你的第一个项目

1. 点击左侧 “Projects”
2. 点击 “New Project”
3. 项目名称：“我的 React 项目”
4. 描述：“一个用 React 做的网站”
5. 点击 “Create Project”

4. 连接 AI 编程助手

如果你用 Cursor：

1. 在 Archon 里点击左侧 “MCP Dashboard”
2. 找到 “Cursor” 的配置
3. 复制那段 JSON
4. 在 Cursor 的设置里，找到 MCP 配置
5. 粘贴进去，重启 Cursor

如果你用 Claude Code：

1. 同样在 MCP Dashboard 找 Claude 的配置
2. 按提示操作

🐛 常见问题解决

问题1：端口被占用

**症状：**启动时报 Port 3737 already in use

解决：

# 先停止所有容器
docker compose down# 修改端口
# 打开 .env 文件，加一行：
ARCHON_UI_PORT=3738# 重新启动
docker compose up -d

问题2：Docker 没权限（Linux）

**症状：**报 permission denied

解决：

# 把用户加入 docker 组
sudo usermod -aG docker $USER# 重新登录

问题3：前端连不上后端

**症状：**网页能打开，但是显示 “Connection failed”

解决：

1. 检查后端是否运行：docker compose ps
2. 检查端口是否正确：打开 .env 看 ARCHON_SERVER_PORT
3. 重启试试：docker compose restart

🎉 进阶使用技巧

1. 批量上传文档

如果你有本地文档：

1. 在 Knowledge Base 点击 “Upload Documents”
2. 可以一次拖多个 PDF、Word、Markdown 文件
3. Archon 会自动提取文字和代码示例

2. 智能搜索

在 Knowledge Base 的搜索框里：

• 直接搜 “React hooks 怎么写”
• 或者用高级搜索：“file:pdf React”
• 甚至可以搜代码片段：“useState 数组更新”

3. 项目管理

• 给任务加标签：#bug #feature #important
• 设置优先级：高、中、低
• AI 可以帮你分解大任务：创建一个任务后，点击 “AI Split”

4. 实时协作

• 邀请团队成员：Settings → Users → Invite
• 多人同时编辑文档
• 实时看到别人的更新

🔄 日常维护

查看日志

# 看所有服务日志
docker compose logs -f# 只看某个服务
docker compose logs -f archon-server

更新到最新版

# 拉最新代码
git pull origin main# 重新构建
docker compose down
docker compose up --build -d

重置数据库（慎用！）

如果你搞坏了数据库：

1. 在 Supabase SQL Editor 运行 migration/RESET_DB.sql
2. 再运行 migration/complete_setup.sql
3. 重启所有服务

📝 总结

现在你已经成功搭建了 Archon！接下来你可以：

1. 继续添加知识：把你常用的文档、API 参考都扔进去
2. 连接更多 AI 工具：Cursor、Claude Code、Windsurf 都行
3. 建立项目：为每个项目建立独立的知识库
4. 分享经验：在 GitHub Discussions 分享你的使用心得

记住，Archon 就像你的"第二大脑"，用得越多越聪明。刚开始可能觉得麻烦，但一旦知识库丰富起来，你就会发现 AI 助手变得超级懂你！

---

恭喜你完成了 Archon 的搭建！ 🎉

现在去喝杯咖啡，享受 AI 助手突然变得超级聪明的感觉吧！