跳到主要内容

🎯 快速开始

本指南将帮助你在本地快速搭建井云项目的开发环境。

📋 环境要求​

必需工具​

  • Go: 1.25.4 或更高版本
  • Node.js: >= 18.0
  • pnpm: >= 9.0.0
  • Docker: 用于启动基础设施服务
  • Docker Compose: 用于编排容器

可选工具​

  • Git: 用于版本控制
  • Make: 用于自动化构建（后端）

1️⃣ 后端服务​

启动基础设施​

后端服务需要以下基础设施支持：

  • PostgreSQL 数据库
  • Redis 缓存
  • RabbitMQ 消息队列
  • Consul 服务注册中心
# 进入后端目录
cd backend

# 启动所有基础设施服务
docker-compose -f deployments/docker-compose.local.yml up -d

# 查看服务状态
docker-compose -f deployments/docker-compose.local.yml ps

基础设施服务访问地址：

构建并运行网关服务​

网关服务是系统的统一入口，其他服务通过 Consul 进行服务注册和发现。

# 进入网关服务目录
cd services/gateway

# 生成所有代码（API、配置、Wire、Ent）
make all

# 运行服务
make run

访问网关服务：http://localhost:8000

其他服务​

其他服务（Auth、User、Tenant、Agent、Payment、Integration、Cron）的启动方式类似：

# 进入服务目录
cd services/<service-name>

# 生成代码
make all

# 运行服务
make run

2️⃣ 前端应用​

安装依赖​

前端项目使用 pnpm workspace 管理多个应用和共享包。

# 进入前端目录
cd frontend

# 安装所有依赖
pnpm install

启动应用​

平台管理应用​

cd hosts/platform
pnpm dev

访问地址：http://localhost:5173

租户管理应用​

cd hosts/tenant
pnpm dev

访问地址：http://localhost:5174

Web 应用​

cd hosts/web
pnpm dev

访问地址：http://localhost:5175

其他应用​

# Agent 应用
cd hosts/agent
pnpm dev

# 小程序应用（H5）
cd hosts/miniApp
pnpm dev

# 官方网站
cd hosts/website
pnpm dev

3️⃣ 文档站点​

安装依赖​

# 进入文档目录
cd docs

# 安装依赖
npm install

启动文档站点​

# 启动开发服务器
npm start

访问文档：http://localhost:3000

🔍 验证安装​

后端服务验证​

# 检查网关服务健康状态
curl http://localhost:8000/health

# 检查 Consul 服务注册
curl http://localhost:8500/v1/catalog/services

前端应用验证​

在浏览器中访问对应的应用地址，确认页面正常加载。

🛠️ 常见问题​

Docker 相关​

Q: Docker 容器启动失败

# 查看容器日志
docker-compose -f deployments/docker-compose.local.yml logs -f <service-name>

# 重启容器
docker-compose -f deployments/docker-compose.local.yml restart <service-name>

Q: 端口被占用

# 查看端口占用
lsof -i :8000
lsof -i :8500

# 修改 docker-compose.local.yml 中的端口映射

后端服务相关​

Q: 服务无法连接数据库

  • 确认 PostgreSQL 容器正在运行
  • 检查数据库连接配置
  • 验证数据库用户名和密码

Q: Consul 服务注册失败

  • 确认 Consul 容器正在运行
  • 检查服务配置中的 Consul 地址
  • 查看服务日志获取详细错误信息

前端应用相关​

Q: 依赖安装失败

# 清理缓存并重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

Q: 开发服务器启动失败

  • 检查端口是否被占用
  • 确认 Node.js 版本 >= 18.0
  • 查看错误日志获取详细信息

📚 下一步​

快速开始后，建议继续阅读：

💡 获取帮助​

如果遇到问题，可以通过以下方式获取帮助：