94 lines
2.6 KiB
Markdown
94 lines
2.6 KiB
Markdown
|
---
|
|||
|
|
title: 开发指南
|
|||
|
|
tags: [开发部署, 开发, 本地开发, 环境搭建]
|
|||
|
|
aliases: [开发环境, DevGuide, 开发指南]
|
|||
|
|
source: 开发指南.md
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 开发指南
|
|||
|
|
|
|||
|
|
## 快速开发模式（推荐）
|
|||
|
|
|
|||
|
|
如果需要频繁修改 `app` 或 `frontend` 代码，不需要每次都重新构建 Docker 镜像，可以使用本地开发模式。
|
|||
|
|
|
|||
|
|
> 详细的开发模式说明参见 [快速开发模式](../开发部署/快速开发模式.md)
|
|||
|
|
|
|||
|
|
### 方式一：使用 Make 命令（推荐）
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 终端 1：启动基础设施
|
|||
|
|
make dev-start
|
|||
|
|
|
|||
|
|
# 终端 2：启动后端
|
|||
|
|
make dev-app
|
|||
|
|
|
|||
|
|
# 终端 3：启动前端
|
|||
|
|
make dev-frontend
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 方式二：使用脚本命令
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
./scripts/dev.sh start # 启动基础设施
|
|||
|
|
./scripts/dev.sh app # 启动后端
|
|||
|
|
./scripts/dev.sh frontend # 启动前端
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 访问地址
|
|||
|
|
|
|||
|
|
| 服务 | 地址 |
|
|||
|
|
|------|------|
|
|||
|
|
| 前端开发服务器 | http://localhost:5173 |
|
|||
|
|
| 后端 API | http://localhost:8080 |
|
|||
|
|
| PostgreSQL | localhost:5432 |
|
|||
|
|
| Redis | localhost:6379 |
|
|||
|
|
| MinIO Console | http://localhost:9001 |
|
|||
|
|
| Neo4j Browser | http://localhost:7474 |
|
|||
|
|
|
|||
|
|
> Neo4j 的使用参见 [知识图谱](../核心功能/知识图谱.md) 和 [开启知识图谱功能](../核心功能/开启知识图谱功能.md)
|
|||
|
|
|
|||
|
|
## 使用 Air 实现后端热重载
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
go install github.com/air-verse/air@latest
|
|||
|
|
make dev-app # 检测到 Air 时自动启用热重载
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 前端独立开发
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd frontend
|
|||
|
|
npm run dev # 连接到 http://localhost:8080 的后端 API
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 生产环境部署
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
sh scripts/build_images.sh # 构建所有镜像
|
|||
|
|
sh scripts/start_all.sh # 启动生产环境
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 常见问题
|
|||
|
|
|
|||
|
|
- **启动 dev-app 时报错连接不到数据库**：确保先运行了 `make dev-start`
|
|||
|
|
- **前端 CORS 错误**：检查 `vite.config.ts` 中的代理配置
|
|||
|
|
- **DocReader 需要重新构建**：`sh scripts/build_images.sh -d`
|
|||
|
|
|
|||
|
|
> 更多排查建议参见 [常见问题](../运维排障/常见问题.md)
|
|||
|
|
|
|||
|
|
## 相关主题
|
|||
|
|
|
|||
|
|
- [快速开发模式](../开发部署/快速开发模式.md) — 开发模式的架构说明
|
|||
|
|
- [知识图谱](../核心功能/知识图谱.md) — 开发环境中的 Neo4j 配置
|
|||
|
|
- [Agent技能系统](../核心功能/Agent技能系统.md) — 沙箱镜像的构建
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 反向链接
|
|||
|
|
|
|||
|
|
- [Home](../Home.md) — Wiki 首页导航
|
|||
|
|
- [快速开发模式](../开发部署/快速开发模式.md) — 开发模式的架构对比说明
|
|||
|
|
- [知识图谱](../核心功能/知识图谱.md) — 开发环境中的 Neo4j 启动
|
|||
|
|
- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 开发环境中启用图谱功能
|
|||
|
|
- [常见问题](../运维排障/常见问题.md) — 开发相关故障排查
|