这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

附录

配置、故障排查等参考信息

附录包含配置参数、故障排查和其他参考信息。

附录内容

配置参数

详细的系统配置说明：

  • 环境变量：所有可配置的环境变量
  • application.yml：Spring Boot 配置文件
  • Docker Compose：容器配置
  • Kubernetes：K8s 配置

故障排查

常见问题的排查步骤和解决方案：

  • 服务启动问题：容器启动失败等
  • 数据库连接问题：数据库连接失败等
  • 前端问题：页面加载、API 请求等
  • 任务执行问题：任务卡住、执行失败等
  • 性能问题：系统响应缓慢、内存溢出等

其他参考

相关资源

技术支持

如果遇到问题：

  1. 查看 故障排查 文档
  2. 搜索 GitHub Issues
  3. 提交新的 Issue 并附上详细信息

贡献指南

欢迎为 DataMate 贡献：

  • 报告 Bug
  • 提出新功能建议
  • 提交代码贡献
  • 改进文档

详见 贡献指南。

1 - 配置参数

DataMate 系统配置参数说明

本文档详细说明 DataMate 的各种配置参数。

环境变量

通用配置

变量名默认值说明
DB_PASSWORDpassword数据库密码
DATAMATE_JWT_ENABLEfalse是否启用 JWT 认证
REGISTRYghcr.io/modelengine-group/镜像仓库地址
VERSIONlatest镜像版本标签

数据库配置

变量名默认值说明
DB_HOSTdatamate-database数据库主机
DB_PORT5432数据库端口
DB_NAMEdatamate数据库名称
DB_USERpostgres数据库用户名
DB_PASSWORDpassword数据库密码

Redis 配置

变量名默认值说明
REDIS_HOSTdatamate-redisRedis 主机
REDIS_PORT6379Redis 端口
REDIS_PASSWORD-Redis 密码（可选）
REDIS_DB0Redis 数据库编号

Milvus 配置

变量名默认值说明
MILVUS_HOSTmilvusMilvus 主机
MILVUS_PORT19530Milvus 端口
MILVUS_INDEX_TYPEIVF_FLAT向量索引类型
MILVUS_EMBEDDING_DIM768向量维度

MinIO 配置

变量名默认值说明
MINIO_ENDPOINTminio:9000MinIO 端点
MINIO_ACCESS_KEYminioadmin访问密钥
MINIO_SECRET_KEYminioadmin秘密密钥
MINIO_BUCKETdatamate存储桶名称
MINIO_USE_SSLfalse是否使用 SSL

LLM 配置

变量名默认值说明
OPENAI_API_KEY-OpenAI API 密钥
OPENAI_BASE_URLhttps://api.openai.com/v1API 基础 URL
OPENAI_MODELgpt-4使用的模型

JWT 配置

变量名默认值说明
JWT_SECRETdefault-insecure-keyJWT 密钥（生产环境必须修改）
JWT_EXPIRATION86400Token 过期时间（秒）

日志配置

变量名默认值说明
LOG_LEVELINFO日志级别
LOG_PATH/var/log/datamate日志路径

application.yml 配置

主配置文件

# application.yml
datamate:
  jwt:
    enable: ${DATAMATE_JWT_ENABLE:false}
    secret: ${JWT_SECRET:default-insecure-key}
    expiration: ${JWT_EXPIRATION:86400}

  storage:
    type: minio  # minio, local, s3
    endpoint: ${MINIO_ENDPOINT:minio:9000}
    access-key: ${MINIO_ACCESS_KEY:minioadmin}
    secret-key: ${MINIO_SECRET_KEY:minioadmin}
    bucket: ${MINIO_BUCKET:datamate}

  llm:
    provider: openai
    api-key: ${OPENAI_API_KEY:}
    base-url: ${OPENAI_BASE_URL:https://api.openai.com/v1}
    model: ${OPENAI_MODEL:gpt-4}
    temperature: 0.7
    max-tokens: 2000

Spring Boot 配置

spring:
  application:
    name: data-management-service

  datasource:
    url: jdbc:postgresql://${DB_HOST:datamate-database}:${DB_PORT:5432}/${DB_NAME:datamate}
    username: ${DB_USER:postgres}
    password: ${DB_PASSWORD:password}
    driver-class-name: org.postgresql.Driver
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000

  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect
        format_sql: true

  redis:
    host: ${REDIS_HOST:datamate-redis}
    port: ${REDIS_PORT:6379}
    password: ${REDIS_PASSWORD:}
    database: ${REDIS_DB:0}
    timeout: 3000
    lettuce:
      pool:
        max-active: 8
        max-idle: 8
        min-idle: 0
        max-wait: -1ms

server:
  port: 8092
  servlet:
    context-path: /api/v1
  compression:
    enabled: true
  tomcat:
    max-threads: 200
    accept-count: 100

日志配置

<!-- logback-spring.xml -->
<configuration>
    <springProperty scope="context" name="LOG_LEVEL" source="log.level" defaultValue="INFO"/>
    <springProperty scope="context" name="LOG_PATH" source="log.path" defaultValue="/var/log/datamate"/>

    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_PATH}/backend/app.log</file>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/backend/app-%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>30</maxHistory>
            <totalSizeCap>10GB</totalSizeCap>
        </rollingPolicy>
    </appender>

    <logger name="com.datamate" level="${LOG_LEVEL}"/>
    <logger name="org.springframework" level="INFO"/>
    <logger name="org.hibernate" level="INFO"/>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="FILE"/>
    </root>
</configuration>

Docker Compose 配置

环境变量配置

# docker-compose.yml
services:
  datamate-backend:
    environment:
      - DB_PASSWORD=${DB_PASSWORD:-password}
      - DATAMATE_JWT_ENABLE=${DATAMATE_JWT_ENABLE:-false}
      - LOG_LEVEL=${LOG_LEVEL:-INFO}
    volumes:
      - dataset_volume:/dataset
      - log_volume:/var/log/datamate

资源限制配置

services:
  datamate-backend:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

Kubernetes 配置

ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: datamate-config
data:
  DB_HOST: "datamate-database"
  DB_PORT: "5432"
  REDIS_HOST: "datamate-redis"
  REDIS_PORT: "6379"
  LOG_LEVEL: "INFO"

Secret

apiVersion: v1
kind: Secret
metadata:
  name: datamate-secret
type: Opaque
data:
  DB_PASSWORD: cGFzc3dvcmQ=  # base64 encoded
  JWT_SECRET: eW91ci1zZWNyZXQta2V5
  OPENAI_API_KEY: eW91ci1hcGkta2V5

环境变量引用

apiVersion: apps/v1
kind: Deployment
metadata:
  name: datamate-backend
spec:
  template:
    spec:
      containers:
        - name: backend
          env:
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: datamate-secret
                  key: DB_PASSWORD
            - name: LOG_LEVEL
              valueFrom:
                configMapKeyRef:
                  name: datamate-config
                  key: LOG_LEVEL

前端配置

环境变量

# .env.development
VITE_API_BASE_URL=http://localhost:8080
VITE_API_TIMEOUT=30000
VITE_APP_TITLE=DataMate Dev

# .env.production
VITE_API_BASE_URL=https://api.datamate.com
VITE_API_TIMEOUT=30000
VITE_APP_TITLE=DataMate

Vite 配置

// vite.config.ts
export default defineConfig({
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: env.VITE_API_BASE_URL,
        changeOrigin: true,
      },
    },
  },
  build: {
    outDir: 'dist',
    sourcemap: false,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom', 'react-router-dom'],
          antd: ['antd'],
        },
      },
    },
  },
});

Python 运行时配置

环境变量

# Python 服务配置
PG_HOST=datamate-database
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=password
PG_DATABASE=datamate

log_level=DEBUG
datamate_jwt_enable=false

配置文件

# config.py
import os

class Config:
    # PostgreSQL
    PG_HOST = os.getenv('PG_HOST', 'datamate-database')
    PG_PORT = int(os.getenv('PG_PORT', 5432))
    PG_USER = os.getenv('PG_USER', 'postgres')
    PG_PASSWORD = os.getenv('PG_PASSWORD', 'password')
    PG_DATABASE = os.getenv('PG_DATABASE', 'datamate')

    # 日志
    LOG_LEVEL = os.getenv('log_level', 'INFO')

    # JWT
    JWT_ENABLE = os.getenv('datamate_jwt_enable', 'false').lower() == 'true'

    # Milvus
    MILVUS_HOST = os.getenv('MILVUS_HOST', 'milvus')
    MILVUS_PORT = int(os.getenv('MILVUS_PORT', 19530))

性能调优参数

数据库连接池

spring:
  datasource:
    hikari:
      maximum-pool-size: 20      # 最大连接数
      minimum-idle: 5            # 最小空闲连接数
      connection-timeout: 30000  # 连接超时（毫秒）
      idle-timeout: 600000       # 空闲超时（毫秒）
      max-lifetime: 1800000      # 连接最大生命周期（毫秒）

Redis 连接池

spring:
  redis:
    lettuce:
      pool:
        max-active: 8      # 最大活跃连接数
        max-idle: 8        # 最大空闲连接数
        min-idle: 0        # 最小空闲连接数
        max-wait: -1ms     # 最大等待时间

JVM 参数

# JVM 调优参数
JAVA_OPTS="-Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

相关文档

2 - 故障排查

DataMate 常见问题和解决方案

本文档提供 DataMate 常见问题的排查步骤和解决方案。

服务启动问题

服务无法启动

症状

执行 make install 后，服务无法启动或立即退出。

排查步骤

  1. 检查端口占用
# 检查端口是否被占用
lsof -i :8080  # API Gateway
lsof -i :30000 # Frontend
lsof -i :5432  # PostgreSQL

如果端口被占用：

# 查找占用进程
ps aux | grep <port>

# 终止进程
kill -9 <PID>
  1. 查看容器日志
# 查看所有容器状态
docker ps -a

# 查看特定容器日志
docker logs datamate-backend
docker logs datamate-frontend
docker logs datamate-database
  1. 检查 Docker 资源
# 查看 Docker 系统信息
docker system df

# 清理未使用的资源
docker system prune -a

常见原因和解决方案

原因解决方案
端口被占用终止占用进程或修改端口映射
内存不足增加 Docker 内存限制
镜像未拉取执行 docker pull 拉取镜像
网络问题检查防火墙和网络配置

容器启动后立即退出

排查步骤

# 查看容器退出码
docker ps -a

# 查看详细日志
docker logs <container-name> --tail 100

# 检查容器健康状态
docker inspect <container-name> | grep -A 10 Health

常见原因

  • 配置错误：检查环境变量和配置文件
  • 依赖服务未启动：确保数据库等依赖服务已启动
  • 资源不足：检查内存和磁盘空间

数据库连接问题

无法连接到数据库

症状

后端服务日志显示数据库连接错误。

排查步骤

  1. 检查数据库容器
# 检查数据库容器状态
docker ps | grep datamate-database

# 查看数据库日志
docker logs datamate-database
  1. 测试数据库连接
# 进入数据库容器
docker exec -it datamate-database psql -U postgres -d datamate

# 或从本地连接
psql -h localhost -U postgres -d datamate
  1. 检查数据库配置
# 检查环境变量
docker exec datamate-backend env | grep DB_

# 检查配置文件
docker exec datamate-backend cat /app/application.yml | grep datasource

常见解决方案

问题解决方案
密码错误检查 DB_PASSWORD 环境变量
数据库未就绪等待数据库完全启动
网络不通检查 Docker 网络
连接池耗尽增加连接池大小

数据库性能问题

症状

查询缓慢，数据库响应时间长。

排查步骤

  1. 查看慢查询
-- 查看慢查询
SELECT query, mean_exec_time, calls
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;
  1. 检查连接数
-- 查看当前连接数
SELECT count(*) FROM pg_stat_activity;

-- 查看最大连接数
SHOW max_connections;
  1. 分析表大小
-- 查看表大小
SELECT
    relname AS table_name,
    pg_size_pretty(pg_total_relation_size(relid)) AS size
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC;

优化方案

  • 添加索引
  • 优化查询语句
  • 增加连接池大小
  • 定期清理和分析表

前端问题

前端无法访问

症状

浏览器无法访问 http://localhost:30000

排查步骤

  1. 检查前端容器
docker ps | grep datamate-frontend
docker logs datamate-frontend
  1. 检查端口映射
# 查看端口映射
docker port datamate-frontend
  1. 测试网络连接
# 测试容器内部服务
docker exec datamate-frontend wget -O- http://localhost:3000

常见解决方案

  • 检查端口是否正确映射
  • 检查防火墙设置
  • 查看浏览器控制台错误信息
  • 清除浏览器缓存

API 请求失败

症状

前端页面显示，但 API 请求失败。

排查步骤

  1. 检查浏览器控制台
// 查看网络请求
// 开发者工具 -> Network 标签
  1. 检查 API Gateway
# 检查 API Gateway 容器
docker ps | grep datamate-gateway
docker logs datamate-gateway
  1. 测试 API
# 测试 API 连接
curl http://localhost:8080/actuator/health

# 测试 API 端点
curl http://localhost:8080/api/v1/data-management/datasets

常见解决方案

错误解决方案
CORS 错误配置 API Gateway CORS
401 Unauthorized检查认证配置
404 Not Found检查 API 路径配置
503 Service Unavailable检查后端服务状态

任务执行问题

任务卡住不动

症状

任务状态一直为"运行中"，但没有任何进展。

排查步骤

  1. 查看任务日志
# 查看后端服务日志
docker logs datamate-backend --tail 100 | grep <task-id>

# 查看运行时日志
docker logs datamate-runtime --tail 100
  1. 检查任务状态
# 通过 API 查询任务状态
curl http://localhost:8080/api/v1/data-cleaning/tasks/<task-id>
  1. 检查系统资源
# 检查 CPU 和内存使用
docker stats

# 检查磁盘空间
df -h

常见原因和解决方案

原因解决方案
算子执行失败查看运行时日志，修复算子代码
数据量过大分批处理
资源不足增加容器资源限制
死锁重启服务

任务执行失败

排查步骤

  1. 查看详细错误日志
# 查看任务执行日志
docker logs datamate-backend | grep ERROR
  1. 检查任务配置
# 查看任务配置
curl http://localhost:8080/api/v1/data-cleaning/tasks/<task-id>
  1. 验证输入数据

检查输入数据格式和内容是否正确。

性能问题

系统响应缓慢

排查步骤

  1. 检查系统资源
# 查看 CPU、内存使用
docker stats

# 查看磁盘 I/O
docker exec datamate-backend iostat -x 1
  1. 检查数据库性能
-- 查看活跃查询
SELECT * FROM pg_stat_activity WHERE state = 'active';

-- 查看锁等待
SELECT * FROM pg_stat_activity WHERE wait_event_type = 'Lock';
  1. 检查 Redis 状态
# 查看 Redis 信息
docker exec datamate-redis redis-cli INFO

# 查看慢查询
docker exec datamate-redis redis-cli SLOWLOG GET

优化方案

  • 增加容器资源限制
  • 优化数据库查询
  • 启用缓存
  • 使用负载均衡

内存溢出

症状

容器因内存不足被 OOM Killer 终止。

排查步骤

# 查看容器退出原因
docker inspect <container> | grep OOMKilled

# 查看内存使用历史
docker stats --no-stream

解决方案

# 增加内存限制
services:
  datamate-backend:
    deploy:
      resources:
        limits:
          memory: 8G  # 增加内存限制

日志查看

查看应用日志

# 后端日志
docker logs datamate-backend --tail 100 -f

# 前端日志
docker logs datamate-frontend --tail 100 -f

# 数据库日志
docker logs datamate-database --tail 100 -f

# 运行时日志
docker logs datamate-runtime --tail 100 -f

查看特定级别日志

# 只查看错误日志
docker logs datamate-backend 2>&1 | grep ERROR

# 查看警告日志
docker logs datamate-backend 2>&1 | grep WARN

日志文件位置

服务日志路径
后端/var/log/datamate/backend/app.log
前端/var/log/datamate/frontend/
数据库/var/log/datamate/database/
运行时/var/log/datamate/runtime/

获取帮助

如果以上方法都无法解决问题：

  1. 收集信息

    • 错误信息
    • 日志文件
    • 系统环境
    • 复现步骤

  2. 搜索已有问题

访问 GitHub Issues 搜索类似问题。

  1. 提交新 Issue

在 GitHub 提交 Issue 时，请提供：

  • DataMate 版本
  • 操作系统版本
  • Docker 版本
  • 详细的错误信息
  • 复现步骤

相关文档