kuberlab/training-agent

Training Agent App 镜像文档

镜像概述

Training Agent App是一个集成前后端的应用镜像，基于React TypeScript构建前端界面，Node.js提供后端服务，结合PostgreSQL数据库和Builder API实现AI驱动的培训计划生成。该镜像采用安全架构设计，所有敏感凭证均在服务端处理，确保数据安全和系统稳定。

核心功能与特性

架构特点

• 安全前后端分离：React单页应用前端与Node.js后端分离，通过安全API通信
• 高性能数据存储：采用PostgreSQL数据库直接操作，替代Supabase提升性能
• AI能力集成：服务端集成Builder API，实现培训计划的AI生成
• 多模式运行：支持连接模式（使用真实API）和演示模式（使用模拟数据）

核心功能

• 安全凭证管理：Builder API凭证在服务端安全处理，避免前端暴露
• 数据集管理：通过后端API浏览、选择和管理可用数据集
• AI培训计划：利用Builder API生成全面的定制化培训计划
• 交互式学习：学员界面支持进度跟踪和测验功能
• 角色权限控制：区分管理员和学员角色，提供相应操作权限
• 培训材料管理：生成、审核和批准培训材料的完整流程
• 实时状态监控：显示后端服务连接状态和API可用性

使用场景

• 企业培训管理：为企业员工生成定制化培训计划并跟踪学习进度
• 教育机构应用：教师可管理课程材料，学生通过交互式界面学习
• 开发测试环境：演示模式下无需API依赖，适合开发和功能测试
• 安全培训系统：严格的权限控制和凭证管理，适用于敏感信息培训

详细使用方法

前提条件

• Docker Engine 20.10+
• Docker Compose (可选，用于多容器部署)
• PostgreSQL数据库实例（或使用容器化PostgreSQL）
• Builder API访问凭证（生产环境需要）

Docker快速部署

单容器部署

bash
docker run -d \
  --name training-agent \
  -p 3001:3001 \  # 后端服务端口
  -p 5173:5173 \  # 前端应用端口
  -e PGHOST=your-postgres-host \
  -e PGPORT=5432 \
  -e PGDATABASE=training_agent \
  -e PGUSER=postgres \
  -e PGPASSWORD=your-postgres-password \
  -e BUILDER_API_TOKEN=your-builder-token \
  -e BUILDER_API_BASE_URL=https://api.builder.example.com \
  training-agent:latest

Docker Compose部署

创建docker-compose.yml文件：

yaml
version: '3.8'

services:
  postgres:
    image: postgres:14-alpine
    container_name: training-agent-db
    environment:
      POSTGRES_DB: training_agent
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secure_password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

  training-agent:
    image: training-agent:latest
    container_name: training-agent-app
    ports:
      - "3001:3001"
      - "5173:5173"
    environment:
      # 数据库配置
      PGHOST: postgres
      PGPORT: 5432
      PGDATABASE: training_agent
      PGUSER: postgres
      PGPASSWORD: secure_password
      # Builder API配置
      BUILDER_API_TOKEN: your-builder-api-token
      BUILDER_API_BASE_URL: https://api.builder.example.com
      BUILDER_IS_WORKSPACE_TOKEN: "false"
      # 服务配置
      PORT: 3001
      FRONTEND_URL: http://localhost:5173
      NODE_ENV: production
    depends_on:
      - postgres
    restart: unless-stopped

volumes:
  postgres-data:

启动服务：

bash
docker-compose up -d

服务启动后，可通过以下地址访问：

• 前端应用：http://localhost:5173
• 后端API：http://localhost:3001

数据库初始化

首次部署需要执行数据库迁移：

bash
docker exec -it training-agent-app npm run migrate:up --prefix server

配置说明

环境变量配置

后端核心配置（必需）

前端配置（可选）

配置注意事项

• 所有敏感凭证（如数据库密码、API令牌）必须通过环境变量注入，避免硬编码
• 生产环境中NODE_ENV应设置为production
• 前端默认使用相对URL与后端通信（如/api/datasets），当前后端部署在同一域名下时无需额外配置
• 未提供Builder API凭证时，应用自动切换到演示模式，使用模拟数据

运行模式说明

连接模式（默认）

• 当提供有效Builder API凭证时自动启用
• 使用真实数据集和AI生成功能
• 提供完整的培训计划生成和管理功能

演示模式

• 当Builder API不可用或未配置时自动启用
• 使用内置模拟数据集和响应
• 适合开发、测试和功能演示
• 所有操作在本地完成，无外部API依赖

故障排除

常见问题解决

后端连接错误

问题：前端显示"后端服务不可用"
解决方法：

1. 检查容器运行状态：docker ps | grep training-agent
2. 查看后端日志：docker logs training-agent-app
3. 验证数据库连接：确保PostgreSQL服务正常且凭证正确
4. 检查后端健康接口：访问http://localhost:3001/api/health

Builder API连接问题

问题：显示"使用演示数据 - Builder API不可用"
解决方法：

1. 验证BUILDER_API_TOKEN是否有效且未过期
2. 检查BUILDER_API_BASE_URL是否正确
3. 确认网络环境可访问Builder API
4. 查看后端日志获取详细错误信息：docker logs training-agent-app | grep builder-api

数据库迁移失败

问题：执行迁移命令时出错
解决方法：

1. 确保数据库服务正常运行
2. 验证数据库凭证是否正确
3. 检查数据库是否已创建：createdb training_agent（针对外部数据库）
4. 查看迁移日志：docker exec -it training-agent-app cat server/logs/migrate.log

核心组件架构

前端组件

• App.tsx：应用主包装器，包含API提供器
• TrainingAgentApp.tsx：主应用逻辑和路由管理
• ApiConfig.tsx：API配置界面
• ApiContext.tsx：API客户端管理的React上下文

后端服务

• Node.js服务器：处理API请求、数据库操作和Builder API集成
• PostgreSQL数据库：存储用户数据、培训计划和学习进度
• API代理层：安全处理Builder API请求，保护敏感凭证

API客户端功能

• 认证管理：支持Bearer令牌和工作区特定令牌
• 数据集操作：列表、上传、下载数据集文件
• AI交互：创建聊天会话、发送消息、获取AI响应
• 时间线管理：创建和处理培训时间线数据