DataOps Platform 部署与运维手册

面向系统部署人员。配合 deployment/ 发布包使用。

1. 部署架构

                    ┌─────────────┐
   用户/前端  ────► │ Nginx :18183 │ ──► Gunicorn :5500 ──► Flask App
                    └─────────────┘              │
                                                 ├── PostgreSQL
                                                 ├── Neo4j
                                                 ├── MinIO
                                                 ├── n8n API
                                                 └── DeepSeek API
Supervisor 守护 ──► scripts/run_dataops.sh
环境变量 ─────────► /etc/dataops-platform/dataops.env

2. 服务器要求

项目	要求
操作系统	Ubuntu 20.04 / 22.04 LTS（推荐）
CPU / 内存	4 核 / 8 GB 及以上（生产建议）
磁盘	50 GB+（含日志与上传目录）
运行用户	`ubuntu`（可通过 `APP_USER` 覆盖）
Python	3.8+

2.1 系统软件安装

sudo apt update
sudo apt install -y python3 python3-venv python3-pip supervisor nginx curl
sudo systemctl enable supervisor
sudo systemctl start supervisor

2.2 外部服务（需提前就绪）

服务	默认地址	用途
PostgreSQL	`192.168.3.143:5432`	业务数据
Neo4j	`192.168.3.143:7687`	图关系
MinIO	`192.168.3.143:9000`	文件存储
n8n	`https://n8n.citupro.com`	工作流
DeepSeek	`https://api.deepseek.com`	LLM

部署前连通性测试：

psql "postgresql://postgres:***@192.168.3.143:5432/dataops" -c "SELECT 1"
curl -s http://192.168.3.143:7474
curl -s http://192.168.3.143:9000/minio/health/live

3. 一键部署流程

3.1 上传发布包

cd /tmp
tar -xzf dataops-platform-release-YYYYMMDD.tar.gz
cd dataops-platform

3.2 执行部署

chmod +x deploy_dataops.sh scripts/*.sh
sudo bash deploy_dataops.sh

首次运行会：

创建 /etc/dataops-platform/dataops.env（来自 dataops.env 模板）
提示编辑配置后重新执行（exit code 2）

3.3 编辑环境变量

sudo vim /etc/dataops-platform/dataops.env
sudo chown root:ubuntu /etc/dataops-platform/dataops.env
sudo chmod 640 /etc/dataops-platform/dataops.env

必须修改的项：

变量	说明
`SECRET_KEY`	Flask 密钥，长随机字符串
`DEEPSEEK_API_KEY`	DeepSeek API 密钥
`N8N_API_KEY`	n8n API 密钥
`DATABASE_URL`	PostgreSQL 连接串
`NEO4J_PASSWORD`	Neo4j 密码
`MINIO_*`	MinIO 四项须匹配同一实例

LLM 配置（DeepSeek 官方格式）：

DEEPSEEK_API_KEY=sk-xxxxxxxx
LLM_BASE_URL=https://api.deepseek.com    # 不要写成 .../v1
LLM_MODEL_NAME=deepseek-v4-pro
LLM_REASONING_EFFORT=high

3.4 再次部署

sudo bash deploy_dataops.sh

成功标志：

脚本输出 健康检查通过
curl http://127.0.0.1:5500/api/system/health 返回 HTTP 200

3.5 配置 Nginx（公网访问）

# 修改 SSL 证书路径
sudo vim /etc/nginx/sites-available/dataops-platform.conf

sudo nginx -t
sudo systemctl reload nginx

或使用部署脚本自动生成（HTTP，不含 SSL）：

sudo ENABLE_NGINX=1 NGINX_SERVER_NAME=company.citupro.com NGINX_LISTEN_PORT=18183 bash deploy_dataops.sh

Nginx 模板 config/nginx-dataops-platform.conf 已包含：

/api/bd/ddlparse 超时 300s（避免 LLM 解析 504）
默认 client_max_body_size 100m

4. Python 依赖

见 requirements.txt，核心依赖：

包	版本	用途
Flask	2.3.3	Web 框架
gunicorn	21.2.0	WSGI 服务器
SQLAlchemy	2.0.23	ORM
psycopg2-binary	2.9.9	PostgreSQL
neo4j	5.26.0	图数据库
minio	7.2.10	对象存储
openai	1.58.1	DeepSeek SDK（OpenAI 兼容）
pdfplumber	0.11.4	PDF 解析

虚拟环境路径：/opt/dataops-platform/venv

重建虚拟环境：

sudo RECREATE_VENV=1 /opt/dataops-platform/scripts/deploy_dataops.sh

5. 目录与权限

路径	权限	说明
`/opt/dataops-platform`	`ubuntu:ubuntu`	应用代码
`/etc/dataops-platform/dataops.env`	`640 root:ubuntu`	环境变量
`/data/upload`	`ubuntu:ubuntu`	上传目录
`/data/archive`	`ubuntu:ubuntu`	归档目录
`/opt/dataops-platform/logs`	`ubuntu:ubuntu`	应用日志

6. 运维命令

# 服务管理
sudo supervisorctl status dataops-platform
sudo /opt/dataops-platform/scripts/restart_dataops.sh

# 日志
tail -f /opt/dataops-platform/logs/flask_production.log
tail -f /opt/dataops-platform/logs/gunicorn_error.log
tail -f /var/log/supervisor/dataops-platform.log

# 健康与翻译测试
curl http://127.0.0.1:5500/api/system/health
curl -k -X POST https://company.citupro.com:18183/api/system/translate \
  -H "Content-Type: application/json" \
  -d '{"node_name":"测试宁波数据加工"}'

7. 代码更新（不停机最短流程）

# 1. 上传新版发布包并解压
# 2. 重新部署（会覆盖 app/ 并 pip install）
cd /tmp/dataops-platform
sudo bash deploy_dataops.sh

# 或仅重启（仅改 env 时）
sudo /opt/dataops-platform/scripts/restart_dataops.sh

8. 常见问题

8.1 `$'\r': command not found`

Windows 编辑的脚本/env 含 CRLF。部署脚本已自动转换；手动修复：

sed -i 's/\r$//' /etc/dataops-platform/dataops.env
sed -i 's/\r$//' /opt/dataops-platform/scripts/*.sh

8.2 DeepSeek API Key 未加载

sudo chown root:ubuntu /etc/dataops-platform/dataops.env
sudo chmod 640 /etc/dataops-platform/dataops.env
sudo /opt/dataops-platform/scripts/restart_dataops.sh
grep DEEPSEEK /etc/dataops-platform/dataops.env

8.3 MinIO InvalidAccessKeyId

检查 MINIO_HOST、MINIO_USER、MINIO_PASSWORD 是否指向同一 MinIO 实例，不要混用 127.0.0.1 与生产 IP。

8.4 翻译/DDL 返回中文或 504

确认 DEEPSEEK_API_KEY 有效
确认 LLM_BASE_URL=https://api.deepseek.com（不带 /v1）
Nginx /api/bd/ddlparse 超时 ≥ 300s

8.5 健康检查失败

sudo supervisorctl status dataops-platform
tail -50 /var/log/supervisor/dataops-platform.log
sudo /opt/dataops-platform/scripts/restart_dataops.sh

9. 环境变量完整说明

变量	默认值	说明
`FLASK_ENV`	production	运行模式
`SECRET_KEY`	（必填）	Flask 密钥
`DATABASE_URL`	见 dataops.env	PostgreSQL
`NEO4J_URI`	bolt://192.168.3.143:7687	Neo4j Bolt
`NEO4J_USER` / `NEO4J_PASSWORD`	neo4j / ***	Neo4j 认证
`MINIO_HOST`	192.168.3.143:9000	MinIO 地址
`MINIO_USER` / `MINIO_PASSWORD`	access/secret	MinIO 密钥
`MINIO_BUCKET`	dataops-bucket	存储桶
`DEEPSEEK_API_KEY`	（必填）	DeepSeek API
`LLM_BASE_URL`	https://api.deepseek.com	API 根地址
`LLM_MODEL_NAME`	deepseek-v4-pro	模型名
`LISTEN_PORT`	5500	Gunicorn 端口
`LOG_FILE`	/opt/.../flask_production.log	应用日志绝对路径

完整模板见 dataops.env 与 .env.production.example。

10. 联系与支持

部署完成后请保存：

部署日期与发布包版本（MANIFEST.md）
/etc/dataops-platform/dataops.env 备份（勿提交 Git）
首次健康检查与关键 API 测试结果

详细 API 文档见仓库 docs/ 目录。

DEPLOYMENT_GUIDE.md 7.6 KB История Директен файл