DataOps Platform 生产环境部署与运维手册

1. 系统概述

1.1 项目简介

DataOps Platform 是一个基于 Flask 的数据运营平台，提供数据管理、处理和分析功能。平台集成了 Neo4j 图数据库进行关系管理，并支持 n8n 工作流自动化。

1.2 技术栈

组件	技术	版本
Web 框架	Flask	2.3.3
ORM	SQLAlchemy	2.0.23
关系数据库	PostgreSQL	14+
图数据库	Neo4j	5.x
对象存储	MinIO	-
工作流引擎	n8n	1.116.2
WSGI 服务器	Gunicorn	21.2.0
进程管理	Supervisor	-
反向代理	Nginx	-

1.3 访问地址

服务	地址
DataOps API	`https://company.citupro.com:18183`
n8n 工作流	`https://n8n.citupro.com`
Neo4j Browser	`http://192.168.3.143:7474`
MinIO Console	`http://192.168.3.143:9000`

2. 服务器环境

2.1 服务器信息

项目	值
操作系统	Ubuntu 20.04/22.04 LTS
用户	ubuntu
Python 版本	3.8+
服务器 IP	192.168.3.143

2.2 依赖服务

确保以下服务已安装并运行：

# 检查 Python 版本
python3 --version

# 检查 Supervisor
sudo systemctl status supervisor

# 检查 Nginx
sudo systemctl status nginx

# 检查 PostgreSQL 连接
psql -h 192.168.3.143 -U postgres -d dataops -c "SELECT 1"

# 检查 Neo4j 连接
curl http://192.168.3.143:7474

3. 目录结构

3.1 安装路径

/opt/dataops-platform/           # 应用根目录
├── app/                         # 应用代码
│   ├── api/                     # API 路由
│   │   ├── business_domain/     # 业务领域 API
│   │   ├── data_factory/        # n8n 工作流 API
│   │   ├── data_flow/           # 数据流 API
│   │   ├── data_interface/      # 数据接口 API
│   │   ├── data_source/         # 数据源 API
│   │   ├── graph/               # 图数据 API
│   │   ├── meta_data/           # 元数据 API
│   │   └── system/              # 系统 API
│   ├── config/                  # 配置文件
│   │   ├── config.py            # 主配置
│   │   └── cors.py              # CORS 配置
│   ├── core/                    # 核心业务逻辑
│   ├── models/                  # 数据模型
│   ├── scripts/                 # 数据库脚本
│   └── services/                # 共享服务
├── database/                    # SQL 脚本
├── docs/                        # 文档
├── logs/                        # 应用日志
├── scripts/                     # 运维脚本
│   ├── deploy_dataops.sh        # 部署脚本
│   ├── start_dataops.sh         # 启动脚本
│   ├── stop_dataops.sh          # 停止脚本
│   └── restart_dataops.sh       # 重启脚本
├── tests/                       # 测试文件
├── venv/                        # Python 虚拟环境
├── application.py               # 应用入口（开发用）
├── wsgi.py                      # WSGI 入口（生产用）
├── requirements.txt             # Python 依赖
└── gunicorn.conf.py             # Gunicorn 配置（可选）

3.2 日志路径

日志类型	路径
应用日志	`/opt/dataops-platform/flask_production.log`
Supervisor 日志	`/var/log/supervisor/dataops-platform.log`
Nginx 访问日志	`/var/log/nginx/access.log`
Nginx 错误日志	`/var/log/nginx/error.log`

3.3 配置文件路径

配置	路径
Supervisor	`/etc/supervisor/conf.d/dataops-platform.conf`
Nginx	`/etc/nginx/sites-enabled/dataops-platform.conf`
应用配置	`/opt/dataops-platform/app/config/config.py`

4. 配置参数

4.1 应用配置 (`app/config/config.py`)

生产环境配置 (ProductionConfig)

# Flask 配置
FLASK_ENV = "production"
DEBUG = False
PORT = 80

# PostgreSQL 数据库
SQLALCHEMY_DATABASE_URI = "postgresql://postgres:dataOps@192.168.3.143:5432/dataops"

# Neo4j 图数据库
NEO4J_URI = "bolt://192.168.3.143:7687"
NEO4J_HTTP_URI = "http://192.168.3.143:7474"
NEO4J_USER = "neo4j"
NEO4J_PASSWORD = "cituneo4j"

# MinIO 对象存储
MINIO_HOST = "192.168.3.143:9000"
MINIO_USER = "citu-dataops-acc-key"
MINIO_PASSWORD = "citu-dataops-secret-key"
MINIO_BUCKET = "dataops-bucket"

# n8n 工作流引擎
N8N_API_URL = "https://n8n.citupro.com"
N8N_API_KEY = "<JWT_TOKEN>"
N8N_API_TIMEOUT = 30

# LLM 配置 (阿里云通义千问)
LLM_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
LLM_MODEL_NAME = "qwen-turbo"
LLM_API_KEY = "<API_KEY>"

# 文件路径
UPLOAD_BASE_PATH = "/data/upload"
ARCHIVE_BASE_PATH = "/data/archive"

# 日志配置
LOG_LEVEL = "INFO"
LOG_FILE = "flask_production.log"
LOG_TO_CONSOLE = False

4.2 Supervisor 配置

文件: /etc/supervisor/conf.d/dataops-platform.conf

[program:dataops-platform]
command=/opt/dataops-platform/venv/bin/gunicorn --bind 0.0.0.0:5500 --workers 4 --timeout 120 wsgi:application
directory=/opt/dataops-platform
user=ubuntu
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/supervisor/dataops-platform.log
stdout_logfile_maxbytes=50MB
stdout_logfile_backups=5
environment=FLASK_ENV=production,PATH="/opt/dataops-platform/venv/bin"

配置说明：

参数	值	说明
`--bind`	`0.0.0.0:5500`	监听地址和端口
`--workers`	`4`	Worker 进程数
`--timeout`	`120`	请求超时时间（秒）
`autostart`	`true`	系统启动时自动启动
`autorestart`	`true`	进程异常退出时自动重启

4.3 环境变量（可选）

可以通过环境变量覆盖默认配置：

export FLASK_ENV=production
export DATABASE_URL=postgresql://user:pass@host:5432/db
export NEO4J_URI=bolt://host:7687
export NEO4J_PASSWORD=password
export N8N_API_KEY=your_api_key
export LLM_API_KEY=your_llm_api_key

5. 虚拟环境管理

5.1 虚拟环境路径

/opt/dataops-platform/venv/

5.2 激活虚拟环境

cd /opt/dataops-platform
source venv/bin/activate

5.3 查看已安装的包

source venv/bin/activate
pip list

5.4 安装/更新依赖

source venv/bin/activate
pip install -r requirements.txt

5.5 重建虚拟环境

如果虚拟环境损坏，可以重建：

cd /opt/dataops-platform

# 删除旧的虚拟环境
rm -rf venv

# 创建新的虚拟环境
python3 -m venv venv

# 激活并安装依赖
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

# 验证安装
python -c "from app import create_app; app = create_app(); print('成功')"

5.6 主要依赖包

包名	版本	用途
Flask	2.3.3	Web 框架
Flask-SQLAlchemy	3.1.1	ORM 扩展
SQLAlchemy	2.0.23	ORM
psycopg2-binary	2.9.9	PostgreSQL 驱动
neo4j	5.26.0	Neo4j 驱动
minio	7.2.10	MinIO 客户端
openai	1.58.1	LLM 客户端
gunicorn	21.2.0	WSGI 服务器
pandas	2.0.3	数据处理
loguru	0.7.2	日志

6. 服务管理

6.1 使用运维脚本

cd /opt/dataops-platform

# 启动服务
sudo ./scripts/start_dataops.sh

# 停止服务
sudo ./scripts/stop_dataops.sh

# 重启服务
sudo ./scripts/restart_dataops.sh

6.2 使用 Supervisor 命令

# 查看状态
sudo supervisorctl status dataops-platform

# 启动服务
sudo supervisorctl start dataops-platform

# 停止服务
sudo supervisorctl stop dataops-platform

# 重启服务
sudo supervisorctl restart dataops-platform

# 重新加载配置
sudo supervisorctl reread
sudo supervisorctl update

# 查看实时日志
sudo supervisorctl tail -f dataops-platform

6.3 健康检查

# 本地检查
curl http://127.0.0.1:5500/api/system/health

# 外部检查
curl https://company.citupro.com:18183/api/system/health

正常响应：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "status": "healthy",
    "components": {
      "database": true,
      "neo4j": true,
      "environment": "production",
      "platform": "linux"
    }
  }
}

6.4 代码更新流程

cd /opt/dataops-platform

# 1. 拉取最新代码（如果使用 Git）
git pull origin main

# 2. 激活虚拟环境并更新依赖（如有变更）
source venv/bin/activate
pip install -r requirements.txt

# 3. 重启服务
sudo supervisorctl restart dataops-platform

# 4. 验证服务状态
sudo supervisorctl status dataops-platform
curl http://127.0.0.1:5500/api/system/health

7. 日志管理

7.1 查看日志

# 查看应用日志
tail -f /opt/dataops-platform/flask_production.log

# 查看 Supervisor 日志
tail -f /var/log/supervisor/dataops-platform.log

# 查看最近 100 行日志
tail -100 /var/log/supervisor/dataops-platform.log

# 搜索错误日志
grep -i "error" /var/log/supervisor/dataops-platform.log

7.2 日志级别

生产环境默认日志级别为 INFO，如需调试可临时修改为 DEBUG：

# app/config/config.py
LOG_LEVEL = "DEBUG"  # 改为 DEBUG

修改后重启服务生效。

7.3 日志轮转

Supervisor 自动管理日志轮转：

最大文件大小：50MB
保留备份数：5

8. 常见问题排查

8.1 服务无法启动

检查步骤：

# 1. 检查 Supervisor 状态
sudo supervisorctl status dataops-platform

# 2. 查看错误日志
tail -50 /var/log/supervisor/dataops-platform.log

# 3. 手动测试启动
cd /opt/dataops-platform
source venv/bin/activate
python -c "from app import create_app; app = create_app(); print('成功')"

常见原因：

虚拟环境路径错误
依赖包缺失
配置文件错误
端口被占用

8.2 数据库连接失败

# 测试 PostgreSQL 连接
psql -h 192.168.3.143 -U postgres -d dataops -c "SELECT 1"

# 测试 Neo4j 连接
curl http://192.168.3.143:7474

8.3 n8n API 连接失败

# 测试 n8n API
curl -H "X-N8N-API-KEY: <YOUR_API_KEY>" https://n8n.citupro.com/api/v1/workflows

8.4 依赖包缺失

source venv/bin/activate
pip install <package_name>
sudo supervisorctl restart dataops-platform

8.5 权限问题

# 修复文件权限
sudo chown -R ubuntu:ubuntu /opt/dataops-platform
chmod +x /opt/dataops-platform/scripts/*.sh

9. 备份与恢复

9.1 备份内容

内容	路径/命令
应用代码	`/opt/dataops-platform/`
PostgreSQL 数据库	`pg_dump -h 192.168.3.143 -U postgres dataops > backup.sql`
Neo4j 数据库	Neo4j Admin 导出
MinIO 文件	`mc mirror minio/dataops-bucket ./backup/`

9.2 备份脚本示例

#!/bin/bash
BACKUP_DIR="/data/backup/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR

# 备份代码
tar -czf $BACKUP_DIR/dataops-code.tar.gz /opt/dataops-platform/app

# 备份数据库
pg_dump -h 192.168.3.143 -U postgres dataops > $BACKUP_DIR/dataops-db.sql

echo "备份完成: $BACKUP_DIR"

9.3 恢复数据库

psql -h 192.168.3.143 -U postgres dataops < backup.sql

10. API 接口文档

10.1 系统接口

接口	方法	路径	说明
健康检查	GET	`/api/system/health`	系统健康状态
系统信息	GET	`/api/system/info`	系统配置信息

10.2 工作流接口 (Data Factory)

接口	方法	路径	说明
n8n 健康检查	GET	`/api/datafactory/health`	n8n 连接状态
工作流列表	GET	`/api/datafactory/workflows`	获取工作流列表
工作流详情	GET	`/api/datafactory/workflows/{id}`	获取工作流详情
工作流状态	GET	`/api/datafactory/workflows/{id}/status`	获取工作流状态
激活工作流	POST	`/api/datafactory/workflows/{id}/activate`	激活工作流
停用工作流	POST	`/api/datafactory/workflows/{id}/deactivate`	停用工作流
执行记录列表	GET	`/api/datafactory/executions`	获取执行记录
执行详情	GET	`/api/datafactory/executions/{id}`	获取执行详情
触发工作流	POST	`/api/datafactory/workflows/{id}/execute`	触发工作流执行

10.3 其他 API 模块

模块	前缀	说明
元数据	`/api/meta/`	元数据管理
图数据	`/api/graph/`	Neo4j 图数据操作
数据接口	`/api/interface/`	数据接口管理
数据源	`/api/datasource/`	数据源管理
数据流	`/api/dataflow/`	数据流管理
业务领域	`/api/bd/`	业务领域管理

附录

A. 联系方式

如有问题，请联系运维团队。

B. 更新记录

日期	版本	更新内容
2025-12-25	1.0.0	初始版本，包含完整部署说明

C. 快速命令参考

# 服务管理
sudo supervisorctl status dataops-platform
sudo supervisorctl restart dataops-platform

# 日志查看
tail -f /var/log/supervisor/dataops-platform.log

# 健康检查
curl http://127.0.0.1:5500/api/system/health

# 虚拟环境
source /opt/dataops-platform/venv/bin/activate

PRODUCTION_DEPLOYMENT_GUIDE.md 14 KB Histórico Raw