# DataOps Platform 部署与运维手册

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

---

## 1. 部署架构

```text
                    ┌─────────────┐
   用户/前端  ────► │ 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 系统软件安装

```bash
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 |

部署前连通性测试：

```bash
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 上传发布包

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

### 3.2 执行部署

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

**首次运行**会：

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

### 3.3 编辑环境变量

```bash
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 官方格式）：**

```bash
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 再次部署

```bash
sudo bash deploy_dataops.sh
```

成功标志：

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

### 3.5 配置 Nginx（公网访问）

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

sudo nginx -t
sudo systemctl reload nginx
```

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

```bash
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`

重建虚拟环境：

```bash
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. 运维命令

```bash
# 服务管理
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. 代码更新（不停机最短流程）

```bash
# 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。部署脚本已自动转换；手动修复：

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

### 8.2 DeepSeek API Key 未加载

```bash
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 健康检查失败

```bash
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/` 目录。