DatomsDBS 零到英雄部署和测试指南

版本: 1.0
日期: 2024年12月28日
适用于: DatomsDBS v0.1.0+

📖 概述

本指南将带您从零开始，完成DatomsDBS数据资产管理系统的完整部署、配置和测试。无论您是开发者、系统管理员还是数据工程师，都能通过本指南快速上手DatomsDBS。

🎯 本指南包含内容

快速部署: 5分钟快速启动
完整配置: 生产环境配置优化
全面测试: 验证系统功能的完整性
故障排除: 常见问题解决方案

🚀 第一部分：快速部署 (5分钟上手)

1.1 前置要求

系统要求:

操作系统: Linux, macOS, 或 Windows (WSL推荐)
Node.js: >= 14.0.0 (下载地址)
内存: 最低2GB，推荐4GB+
存储: 最低10GB可用空间

可选要求:

Docker: >= 20.0.0 (用于容器化部署)
Git: 用于代码克隆

1.2 一键安装脚本 ⚡

# 1. 克隆项目
git clone <YOUR_PROJECT_GIT_URL>
cd datomsDBS

# 2. 运行一键设置脚本
./scripts/setup_datomsdbs.sh

# 3. 等待脚本完成，按提示选择启动方式

脚本执行过程:

✅ 系统要求检查 (Node.js, npm, Git)
✅ 自动生成 .env 配置文件
✅ 安装项目依赖
✅ 初始化数据目录
✅ 可选运行基础测试
✅ 选择启动模式

1.3 手动快速启动

如果您偏好手动安装：

# 1. 克隆和进入目录
git clone <YOUR_PROJECT_GIT_URL>
cd datomsDBS

# 2. 安装依赖
npm install

# 3. 复制并配置环境文件
cp .env.example .env
# 或创建基础 .env 文件
cat > .env << EOF
NODE_ENV=development
PORT=9000
JWT_SECRET=your-secret-key-here
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123
EOF

# 4. 启动服务
npm start

1.4 验证部署成功

访问以下地址验证服务状态：

# 检查服务状态
curl http://localhost:9000/api/health

# 预期响应
{
  "status": "ok",
  "version": "0.1.0",
  "timestamp": "2024-12-28T10:00:00.000Z"
}

Web界面访问:

🌐 主服务: http://localhost:9000
🛠️ 管理界面: http://localhost:9000/admin
📚 API文档: http://localhost:9000/api/docs

⚙️ 第二部分：配置详解

2.1 环境变量配置

创建或编辑 .env 文件:

# ===========================================
# 🔧 基础配置
# ===========================================
NODE_ENV=development          # 环境: development/production
PORT=9000                     # 服务端口
LOG_LEVEL=info               # 日志级别: debug/info/warn/error

# ===========================================
# 🔐 安全配置
# ===========================================
JWT_SECRET=your-jwt-secret-here-change-in-production
API_TOKEN=your-api-token-here
ENABLE_AUTH=true             # 启用认证: true/false

# ===========================================
# 👤 管理员配置
# ===========================================
ADMIN_USERNAME=admin         # 管理员用户名
ADMIN_PASSWORD=admin123      # 管理员密码 (生产环境必须修改!)

# ===========================================
# 💾 数据存储
# ===========================================
DATA_DIR=./data              # 数据目录
AUTO_SAVE_INTERVAL=60000     # 自动保存间隔(毫秒)

# ===========================================
# 🤖 AI Agent 配置 (可选)
# ===========================================
LLM_SERVICE_URL=http://localhost:11434
LLM_MODEL_NAME=qwen2:1.5b

# ===========================================
# 🗄️ 数据库配置 (高级功能)
# ===========================================
DB_HOST=localhost
DB_PORT=5432
DB_NAME=datoms_db
DB_USERNAME=postgres
DB_PASSWORD=yourpassword

2.2 Docker部署配置

使用Docker Compose进行容器化部署：

# 启动完整环境 (包含Ollama LLM)
./scripts/start-with-ollama.sh

# 或使用标准Docker Compose
docker-compose up -d

# 查看容器状态
docker-compose ps

# 查看日志
docker-compose logs -f datomsdbs

Docker环境访问地址:

DatomsDBS API: http://localhost:9000
管理界面: http://localhost:9000/admin
Ollama API: http://localhost:11434 (如果启用)

2.3 生产环境配置优化

性能优化配置:

# .env 生产环境配置
NODE_ENV=production
PORT=9000
LOG_LEVEL=warn

# 增加自动保存频率
AUTO_SAVE_INTERVAL=30000

# 启用生产优化
PM2_INSTANCES=4              # 如果使用PM2
MAX_MEMORY_RESTART=1G

安全加固:

# 强密码配置
JWT_SECRET=$(openssl rand -base64 64)
API_TOKEN=$(openssl rand -base64 32)
ADMIN_PASSWORD=$(openssl rand -base64 16)

# 禁用调试
DEBUG=false

🧪 第三部分：全面测试

3.1 系统健康检查

# 基础连通性测试
curl -f http://localhost:9000/api/health || echo "❌ Service health check failed"

# 管理员认证测试
curl -X POST http://localhost:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# 预期响应包含JWT token

3.2 运行测试套件

基于项目的测试目录结构，以下是详细的测试运行指南：

3.2.1 运行所有核心测试

# 运行主要测试套件
npm test                     # 单元测试
npm run test:integration     # 集成测试
npm run test:coverage        # 测试覆盖率

# 运行性能测试
npm run test:load           # 负载测试
npm run test:memory         # 内存泄漏测试

3.2.2 AI Agent系统测试

# Agent功能测试 (核心AI功能)
cd tests/agents
npm install
node agent-test-suite.js

# 或使用便捷脚本
./tests/agents/run-tests.sh

# 验证自然语言查询功能
curl -X POST http://localhost:9000/api/agents/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "type": "natural_language",
    "query": "显示所有数据源",
    "sessionId": "test-session-001"
  }'

3.2.3 数据源连接测试

# 进入数据源测试目录
cd tests/db_source

# 测试MySQL连接
node test-mysql-connection.js

# 测试PostgreSQL连接  
node test-postgres-connection.js

# 测试MongoDB连接
node test-mongodb-connection.js

# 测试文件数据源
node test-file-datasource.js

3.2.4 端到端测试

# 完整流程测试
cd tests/zero_2_hero_test

# 运行端到端测试套件
node complete-workflow-test.js

# 这将测试:
# 1. 用户注册和登录
# 2. 数据源创建
# 3. 数据提取和转换
# 4. 查询和分析
# 5. 权限管理

3.2.5 压力和负载测试

# 负载测试 (使用Artillery)
npm run test:load

# 手动运行特定负载测试
cd tests/load
artillery run config.yml

# 生成测试报告
npm run test:load:report

# 压力测试
cd tests/stress_test
node stress-test-suite.js

3.3 功能验证清单

完成以下功能验证确保系统正常工作：

✅ 基础功能验证

服务启动: 服务在指定端口正常启动
健康检查: /api/health 端点响应正常
管理界面: Web管理界面可访问
API文档: Swagger文档可访问

✅ 认证和授权

管理员登录: 默认admin账户可正常登录
JWT Token: 能够获取和使用JWT token
权限控制: RBAC权限系统工作正常
API访问: 受保护的API需要认证

✅ 数据源管理

创建数据源: 可以添加新的数据源
连接测试: 数据源连接测试功能正常
数据提取: 能够从数据源提取数据
多种格式: 支持CSV、Excel、JSON等格式

✅ AI Agent功能

自然语言查询: 中文/英文查询正常响应
结构化命令: 结构化命令执行正常
会话管理: 多轮对话功能正常
工具调用: Agent能够调用系统工具

✅ 数据存储和查询

DatomsDB: 数据库引擎正常工作
数据写入: 数据事务写入成功
数据查询: Datalog和SQL查询正常
数据持久化: 数据能够持久保存

3.4 性能基准测试

# API响应时间测试
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:9000/api/health

# 并发用户测试
ab -n 1000 -c 10 http://localhost:9000/api/health

# 大数据量导入测试
# 创建大型测试数据集
node tests/optimization/create-large-dataset.js

# 测试导入性能
time node tests/optimization/test-bulk-import.js

🎯 第四部分：验证指南

4.1 基础功能验证

步骤1: 系统访问验证

# 1. 访问主页
open http://localhost:9000

# 2. 登录管理界面
open http://localhost:9000/admin
# 使用 admin/admin123 登录

# 3. 检查API状态
curl http://localhost:9000/api/health

步骤2: 数据源管理验证

创建测试数据源
- 登录管理界面
- 导航到"数据源管理"
- 点击"添加数据源"
- 选择"文件"类型，上传示例CSV文件
验证数据提取
- 确认数据源状态为"已连接"
- 查看提取的数据预览
- 验证schema自动生成

步骤3: AI查询验证

# 获取JWT Token
TOKEN=$(curl -X POST http://localhost:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' \
  | jq -r '.token')

# 测试自然语言查询
curl -X POST http://localhost:9000/api/agents/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "type": "natural_language",
    "query": "显示所有的数据源",
    "sessionId": "test-session"
  }'

4.2 高级功能验证

数据血缘追踪

# 创建数据转换任务
curl -X POST http://localhost:9000/api/data-assets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "测试数据资产",
    "sourceId": "your-source-id",
    "transformations": ["clean", "normalize"]
  }'

# 查询数据血缘
curl http://localhost:9000/api/data-lineage/your-asset-id \
  -H "Authorization: Bearer $TOKEN"

权限管理验证

# 创建新用户
curl -X POST http://localhost:9000/api/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "testpass123",
    "roles": ["viewer"]
  }'

# 测试权限限制
# (使用testuser登录，尝试访问管理功能)

🔧 第五部分：故障排除

5.1 常见问题解决

问题1: 服务启动失败

# 检查端口占用
lsof -i :9000
netstat -tulpn | grep 9000

# 检查Node.js版本
node --version  # 应该 >= 14.0.0

# 检查依赖安装
npm list --depth=0

# 查看详细错误日志
NODE_ENV=development npm start

问题2: 数据库连接失败

# 检查数据目录权限
ls -la data/
chmod 755 data/

# 检查DatomsDB存储
ls -la data/
cat data/db_list.json

# 重新初始化数据库
rm -rf data/
mkdir data
echo "[]" > data/db_list.json
npm start

问题3: AI Agent不响应

# 检查Ollama服务 (如果使用)
curl http://localhost:11434/api/version

# 检查LLM配置
grep LLM .env

# 测试Agent端点
curl -X POST http://localhost:9000/api/agents/status \
  -H "Authorization: Bearer $TOKEN"

问题4: 权限错误

# 重置管理员密码
export ADMIN_PASSWORD=new_password
npm start

# 清除JWT缓存
rm -f ~/.datomsdbs/tokens.json

# 检查RBAC配置
curl http://localhost:9000/api/admin/roles \
  -H "Authorization: Bearer $TOKEN"

5.2 日志和调试

启用详细日志

# 开发环境调试
NODE_ENV=development DEBUG=* npm start

# 设置日志级别
LOG_LEVEL=debug npm start

# 查看实时日志
tail -f server.log
tail -f logs/app.log

性能调试

# 生成heap dump
kill -USR2 <node_process_pid>

# 内存使用监控
node --inspect src/server.js

# 性能分析
node --prof src/server.js

5.3 数据恢复

备份和恢复

# 备份数据
tar -czf datomsdbs-backup-$(date +%Y%m%d).tar.gz data/ logs/

# 恢复数据
tar -xzf datomsdbs-backup-20241228.tar.gz

# 验证数据完整性
node scripts/verify-data-integrity.js

📚 第六部分：下一步和进阶

6.1 生产环境部署

使用PM2进程管理

# 安装PM2
npm install -g pm2

# PM2配置文件 (ecosystem.config.js)
cat > ecosystem.config.js << EOF
module.exports = {
  apps: [{
    name: 'datomsdbs',
    script: 'src/server.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'development'
    },
    env_production: {
      NODE_ENV: 'production',
      PORT: 9000
    }
  }]
}
EOF

# 启动生产环境
pm2 start ecosystem.config.js --env production
pm2 startup  # 设置开机自启
pm2 save

反向代理配置 (Nginx)

# /etc/nginx/sites-available/datomsdbs
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:9000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

6.2 监控和告警

系统监控

# 安装监控工具
npm install -g @pm2/pm2-plus

# 配置监控
pm2 plus

# 健康检查脚本
cat > health-check.sh << EOF
#!/bin/bash
if ! curl -f http://localhost:9000/api/health > /dev/null 2>&1; then
    echo "DatomsDBS service is down!" | mail -s "Alert" admin@yourdomain.com
    pm2 restart datomsdbs
fi
EOF

# 设置定时健康检查
crontab -e
# 添加: */5 * * * * /path/to/health-check.sh

6.3 扩展和定制

自定义连接器开发

// src/connectors/custom-connector.js
class CustomConnector {
  async connect(config) {
    // 实现自定义连接逻辑
  }
  
  async extractData(config, options) {
    // 实现数据提取逻辑
  }
}

自定义Agent工具

// src/agents/tools/custom-tool.js
module.exports = {
  name: 'custom_analysis',
  description: '执行自定义数据分析',
  parameters: {
    type: 'object',
    properties: {
      datasetId: { type: 'string' },
      analysisType: { type: 'string' }
    }
  },
  execute: async (params) => {
    // 实现自定义分析逻辑
  }
}

🎉 总结

恭喜！您已经完成了DatomsDBS的完整部署和测试流程。现在您拥有：

✅ 已完成的配置

完全功能的DatomsDBS实例
配置好的环境变量
验证过的核心功能
运行通过的测试套件

🚀 下一步建议

探索数据源: 连接您的实际数据源
自定义配置: 根据需求调整配置
用户培训: 为团队成员提供使用培训
监控设置: 配置生产环境监控
定期备份: 建立数据备份策略

📞 获取帮助

文档中心: docs/ 目录中的详细文档
API参考: http://localhost:9000/api/docs
社区支持: 查看项目README中的联系信息
问题报告: 通过项目Issue tracker报告问题

🔗 相关文档链接:

本指南会持续更新，建议定期查看最新版本

📖 概述​

🎯 本指南包含内容​

🚀 第一部分：快速部署 (5分钟上手)​

1.1 前置要求​

1.2 一键安装脚本 ⚡​

1.3 手动快速启动​

1.4 验证部署成功​

⚙️ 第二部分：配置详解​

2.1 环境变量配置​

2.2 Docker部署配置​

2.3 生产环境配置优化​

🧪 第三部分：全面测试​

3.1 系统健康检查​

3.2 运行测试套件​

3.2.1 运行所有核心测试​

3.2.2 AI Agent系统测试​

3.2.3 数据源连接测试​

3.2.4 端到端测试​

3.2.5 压力和负载测试​

3.3 功能验证清单​

✅ 基础功能验证​

✅ 认证和授权​

✅ 数据源管理​

✅ AI Agent功能​

✅ 数据存储和查询​

3.4 性能基准测试​

🎯 第四部分：验证指南​

4.1 基础功能验证​

步骤1: 系统访问验证​

步骤2: 数据源管理验证​

步骤3: AI查询验证​

4.2 高级功能验证​

数据血缘追踪​

权限管理验证​

🔧 第五部分：故障排除​

5.1 常见问题解决​

问题1: 服务启动失败​

问题2: 数据库连接失败​

问题3: AI Agent不响应​

问题4: 权限错误​

5.2 日志和调试​

启用详细日志​

性能调试​

5.3 数据恢复​

备份和恢复​

📚 第六部分：下一步和进阶​

6.1 生产环境部署​

使用PM2进程管理​

反向代理配置 (Nginx)​

6.2 监控和告警​

系统监控​

6.3 扩展和定制​

自定义连接器开发​

自定义Agent工具​

🎉 总结​

✅ 已完成的配置​

🚀 下一步建议​

📞 获取帮助​