# uctoo-docker

**Repository Path**: UCT/uctoo-docker

## Basic Information

- **Project Name**: uctoo-docker
- **Description**: uctoo 云原生部署，支持标准云原生PaaS公有云的一键部署
- **Primary Language**: Docker
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 9
- **Forks**: 1
- **Created**: 2021-04-11
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: docker-related

**Tags**: None

## README

# UCToo Docker

UCToo V3 版本的云原生部署项目，支持 UCToo 产品体系的完整容器化部署，包括后端服务、前端应用、Agent Skills 运行时等所有核心组件。

## 项目概述

本项目基于 Docker Compose 实现 UCToo V3 版本的完整部署，包含以下服务：

- **PostgreSQL**：关系型数据库，存储系统数据
- **Redis**：缓存服务，提升系统性能
- **Backend**：后端 API 服务，基于 Node.js/TypeScript
- **Frontend**：前端 Web 应用，基于 Vue 3
- **Agent Skills Runtime**：AI 技能运行时，基于仓颉编程语言

## 系统架构

UCToo V3 采用分层架构设计，各组件之间通过明确的接口进行通信：

1. **用户交互层**：前端应用 (uctoo-app-client-pc)，提供用户界面和实时通信
2. **后端服务层**：后端 API 服务 (backend)，处理业务逻辑和数据操作
3. **运行时内核层**：Agent Skills 运行时 (agentskills-runtime)，提供 AI 技能执行环境
4. **数据存储层**：PostgreSQL 数据库和 Redis 缓存

### 通信流程

- **前端 ↔ 后端**：通过 HTTP 请求进行 API 调用
- **前端 ↔ Agent Skills 运行时**：通过 WebSocket 直接通信，实现实时聊天和技能执行
- **后端 ↔ 数据库**：通过 Prisma ORM 进行数据库操作

### 关键端口

- **8080**：Agent Skills 运行时 WebSocket 端口，前端直接连接
- **3000**：后端 API 服务端口
- **5173**：前端应用端口
- **5432**：PostgreSQL 数据库端口
- **6379**：Redis 缓存端口
## 技术栈

- **操作系统**：Ubuntu 22.04 LTS
- **容器化**：Docker + Docker Compose
- **数据库**：PostgreSQL 15
- **缓存**：Redis 7
- **后端**：Node.js 20 + TypeScript + Hyper-Express + Prisma
- **前端**：Vue 3 + TypeScript + Vite + Ant Design Vue
- **AI 运行时**：仓颉编程语言 + Agent Skills Runtime

## 快速开始

### 环境要求

#### 基础依赖

- **Git**：版本控制工具，用于克隆项目代码
- **Docker**：版本 20.10+，用于容器化部署
- **Docker Compose**：版本 1.29+，用于编排多容器服务
- **Curl**：用于下载依赖和测试服务
- **Node.js**：版本 20+（可选，仅当需要在本地开发时）
- **pnpm**：版本 9+（可选，仅当需要在本地开发时）

#### 操作系统支持

- **Windows**：Windows 10 或 Windows 11，需要启用 WSL 2 或 Hyper-V
- **macOS**：macOS 10.15 或更高版本
- **Linux**：Ubuntu 20.04+、CentOS 7+ 或其他支持 Docker 的 Linux 发行版

#### 硬件要求

- **CPU**：至少 2 核处理器
- **内存**：至少 4GB RAM
- **磁盘**：至少 20GB 可用空间
- **网络**：稳定的网络连接，用于下载依赖和镜像

### 部署步骤

#### 方法一：直接使用 uctoo-docker 项目（推荐）

1. **克隆 uctoo-docker 项目**

```bash
git clone https://gitee.com/UCT/uctoo-docker.git
cd uctoo-docker
```

2. **配置环境变量**

复制 `.env.example` 文件为 `.env` 并根据需要修改配置：

```bash
cp .env.example .env
# 编辑 .env 文件，设置必要的环境变量
```

3. **启动服务**

```bash
docker-compose up -d
```

4. **初始化数据库**

服务启动后，需要初始化数据库：

```bash
docker-compose exec backend pnpm init:backend
```

#### 方法二：从主项目构建

1. **克隆主项目**

```bash
git clone https://gitee.com/uctoo/uctoo.git
cd uctoo
```

2. **进入 uctoo-docker 目录**

```bash
cd apps/uctoo-docker
```

3. **配置环境变量**

```bash
cp .env.example .env
# 编辑 .env 文件
```

4. **启动服务**

```bash
docker-compose up -d
```

5. **初始化数据库**

```bash
docker-compose exec backend pnpm init:backend
```

### 访问应用

打开浏览器访问以下地址：

- **前端应用**：http://localhost:5173  
- **后端 API**：http://localhost:3000  
- **Agent Skills 运行时**：http://localhost:8080

### 系统初始化流程

1. **启动所有服务**：执行 `docker-compose up -d` 启动所有容器
2. **初始化数据库**：执行 `docker-compose exec backend pnpm init:backend` 初始化数据库结构和基础数据
3. **验证服务状态**：
   - 访问 http://localhost:3000 确认后端服务正常运行
   - 访问 http://localhost:5173 确认前端应用正常加载
   - 访问 http://localhost:8080 确认 Agent Skills 运行时正常启动

### Agent Skills 运行时使用

1. **技能安装**：通过前端应用的技能管理界面安装新技能
2. **技能执行**：在聊天界面中，智能体会根据用户需求自动选择和执行合适的技能
3. **实时聊天**：与智能体进行实时对话，获取技能执行结果

### 通信测试

要测试前端与 Agent Skills 运行时的 WebSocket 连接：

1. 打开前端应用 (http://localhost:5173)
2. 导航到聊天界面
3. 发送一条消息，系统应该显示智能体的回复
4. 检查浏览器开发者工具的网络标签页，确认 WebSocket 连接成功建立

## 全流程指南：从下载到与 Agent 聊天

### 步骤 1：准备环境

1. **安装基础依赖**
   - 安装 Git：用于克隆项目代码
   - 安装 Docker：版本 20.10+，用于容器化部署
   - 安装 Docker Compose：版本 1.29+，用于编排多容器服务

2. **验证环境**
   ```bash
   git --version
   docker --version
   docker-compose --version
   ```

### 步骤 2：获取项目代码

选择以下方法之一获取项目代码：

#### 方法 A：直接使用 uctoo-docker 项目
```bash
git clone https://gitee.com/UCT/uctoo-docker.git
cd uctoo-docker
```

#### 方法 B：从主项目获取
```bash
git clone https://gitee.com/uctoo/uctoo.git
cd uctoo/apps/uctoo-docker
```

### 步骤 3：配置环境

1. **复制环境变量文件**
   ```bash
   cp .env.example .env
   ```

2. **编辑环境变量文件**
   - 设置数据库连接参数
   - 设置 API 服务地址
   - 设置 Agent Skills 运行时地址
   - 设置其他必要的环境变量

### 步骤 4：启动服务

1. **启动所有容器**
   ```bash
   docker-compose up -d
   ```

2. **等待服务启动**
   - 首次启动需要下载镜像和构建容器，可能需要几分钟时间

3. **检查服务状态**
   ```bash
   docker-compose ps
   ```

### 步骤 5：初始化系统

1. **初始化数据库**
   ```bash
   docker-compose exec backend pnpm init:backend
   ```

2. **验证数据库初始化**
   - 检查后端容器日志，确认数据库初始化成功

### 步骤 6：访问应用

1. **打开前端应用**
   - 访问 http://localhost:5173

2. **登录系统**
   - 使用默认账号：demo / 123456

### 步骤 7：与 Agent 聊天

1. **导航到聊天界面**
   - 在左侧菜单中找到并点击 "聊天" 或 "智能助手"

2. **发送消息**
   - 在聊天输入框中输入一条消息，例如："你好，我想了解这个系统"
   - 点击发送按钮

3. **查看回复**
   - 智能体应该会自动回复你的消息
   - 如果需要，智能体会调用相关技能来回答你的问题

4. **验证 WebSocket 连接**
   - 打开浏览器开发者工具
   - 切换到 "技能运行时状态" 标签页
   - 确认 WebSocket 连接已成功建立（状态为 101 Switching Protocols）

### 步骤 8：验证技能执行

1. **测试技能调用**
   - 发送一条需要技能执行的消息，例如："帮我分析一下这个问题"
   - 观察智能体是否会调用相关技能

2. **查看技能执行结果**
   - 智能体应该会显示技能执行的结果
   - 如果技能执行失败，会显示错误信息

### 常见问题排查

1. **服务启动失败**
   - 检查容器日志：`docker-compose logs <服务名称>`
   - 确保端口未被占用
   - 确保环境变量配置正确

2. **数据库初始化失败**
   - 检查 PostgreSQL 容器是否正常运行
   - 检查数据库连接参数是否正确
   - 检查后端容器日志获取详细错误信息

3. **WebSocket 连接失败**
   - 确保 Agent Skills 运行时服务正常启动
   - 检查前端配置的 WebSocket 地址是否正确
   - 检查防火墙是否阻止了 WebSocket 连接

4. **智能体无响应**
   - 检查 Agent Skills 运行时服务是否正常运行
   - 检查大模型配置是否正确
   - 检查网络连接是否稳定

## 配置参考

### 环境变量配置

#### 数据库配置
- `POSTGRES_DB`：数据库名称
- `POSTGRES_USER`：数据库用户名
- `POSTGRES_PASSWORD`：数据库密码
- `DATABASE_URL`：数据库连接字符串

#### 后端配置
- `NODE_ENV`：运行环境（development/production）
- `API_URL`：API 服务地址
- `JWT_SECRET`：JWT 密钥

#### 前端配置
- `VITE_GLOB_API_URL`：后端 API 地址
- `VITE_AGENTSILLS_RUNTIME_URL`：Agent Skills 运行时地址

#### Agent Skills 运行时配置
- `PORT`：运行时端口
- `HOST`：运行时主机地址

### 端口配置

| 服务 | 内部端口 | 外部端口 | 用途 |
|------|---------|---------|------|
| PostgreSQL | 5432 | 5432 | 数据库服务 |
| Redis | 6379 | 6379 | 缓存服务 |
| Backend | 3000 | 3000 | 后端 API 服务 |
| Frontend | 5173 | 5173 | 前端 Web 应用 |
| Agent Skills | 8080 | 8080 | AI 技能运行时 |

### 默认账号

- **用户名**：admin
- **密码**：123456

## 服务配置

### 服务端口

| 服务 | 内部端口 | 外部端口 | 访问地址 |
|------|---------|---------|----------|
| PostgreSQL | 5432 | 5432 | localhost:5432 |
| Redis | 6379 | 6379 | localhost:6379 |
| Backend | 3000 | 3000 | localhost:3000 |
| Frontend | 5173 | 5173 | localhost:5173 |
| Agent Skills | 8080 | 8080 | localhost:8080 |

### 环境变量

主要环境变量配置：

- **数据库配置**：`POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`
- **后端配置**：`DATABASE_URL`, `REDIS_URL`, `API_URL`, `JWT_SECRET`
- **前端配置**：`VITE_GLOB_API_URL`, `VITE_AGENTSILLS_RUNTIME_URL`
- **Agent Skills 配置**：`AGENTSILLS_PORT`, `AGENTSILLS_HOST`

## 管理命令

### 启动/停止服务

```bash
# 启动所有服务
docker-compose up -d

# 停止所有服务
docker-compose down

# 重启所有服务
docker-compose restart
```

### 查看日志

```bash
# 查看所有服务日志
docker-compose logs

# 查看特定服务日志
docker-compose logs backend
```

### 进入容器

```bash
# 进入后端容器
docker-compose exec backend bash

# 进入前端容器
docker-compose exec frontend bash
```

## 数据库管理

### 初始化数据库

```bash
docker-compose exec backend pnpm init:backend
```

### 生成 Prisma Client

```bash
docker-compose exec backend pnpm prisma:generate
```

### 打开 Prisma Studio

```bash
docker-compose exec backend pnpm prisma:studio
```

## 开发模式

### 开发环境启动

```bash
# 启动开发模式服务
docker-compose -f docker-compose.dev.yml up -d
```

### 代码更新

当代码更新后，需要重新构建容器：

```bash
# 重新构建后端服务
docker-compose build backend
docker-compose restart backend

# 重新构建前端服务
docker-compose build frontend
docker-compose restart frontend
```

## 生产环境部署

### 生产环境配置

复制 `docker-compose.prod.yml.example` 文件为 `docker-compose.prod.yml` 并根据生产环境需求修改配置：

```bash
cp docker-compose.prod.yml.example docker-compose.prod.yml
# 编辑 docker-compose.prod.yml 文件
```

### 生产环境启动

```bash
docker-compose -f docker-compose.prod.yml up -d
```

## 云平台部署

### 腾讯云 CloudBase

1. 登录 [腾讯云 CloudBase](https://console.cloud.tencent.com/tcb)
2. 创建新的 CloudBase 环境
3. 上传 `cloudbaserc.json` 文件
4. 点击部署按钮

### 华为云

华为云一键部署特性开发中，敬请期待。

## 监控与维护

### 健康检查

```bash
# 检查后端服务健康状态
docker-compose exec backend curl http://localhost:3000/health

# 检查数据库连接
docker-compose exec backend pnpm prisma:check
```

### 性能监控

推荐使用以下工具监控系统性能：

- **Prometheus**：监控系统指标
- **Grafana**：可视化监控数据
- **ELK Stack**：日志管理与分析

## 安全建议

1. **修改默认密码**：生产环境中务必修改默认账号密码
2. **配置 HTTPS**：生产环境中启用 SSL 证书
3. **限制访问**：配置防火墙，只允许必要的端口访问
4. **定期备份**：定期备份数据库，防止数据丢失
5. **更新依赖**：定期更新系统依赖，修复安全漏洞

## 文档

详细文档请查看 `docs/` 目录。

## 问题反馈

如有问题，请在 [Gitee Issues](https://gitee.com/UCT/uctoo-docker/issues) 中反馈。

## 许可证

本项目采用 MIT 许可证。