风险监控 API 服务部署

1. 概述
   本文档旨在指导如何将基于 Python Flask 和 PyMySQL 开发的风险监控 API 服务部署到 CentOS 服务器上。该服务负责查询客户逾期数据，并调用 AI Agent API 生成风险分析摘要。

2. 部署前准备
   2.1. 服务器环境要求
   操作系统： CentOS 7/8 或更高版本。
   网络：
   服务器需能访问外部 AI Agent API ([REDACTED])。
   服务器需能访问内部 MySQL 数据库 ([REDACTED])。
   开放必要端口：
   80 (HTTP) / 443 (HTTPS) - 用于 Nginx 反向代理。
   5000 (或其他您选择的端口) - 如果直接运行 Flask/Gunicorn，但推荐使用 Nginx。
   MySQL 数据库端口 (默认为 3306) - 如果数据库不在本地。
   软件：
   Conda (Miniconda/Anaconda)： 已安装并配置好，conda 命令可用。
   Nginx： 已安装并运行。
   Git (可选)： 用于从代码仓库拉取代码。
   SSH 访问： 具备服务器的 SSH 登录权限。
   2.2. 代码准备
   代码文件： app.py (包含 Flask 应用逻辑)。
   依赖文件： requirements.txt (列出所有 Python 依赖)。
   配置文件： .env 文件 (用于存储敏感信息，如 API Key 和数据库密码)。
   2.3. 敏感信息配置

.env 文件示例：
DOTENV
# AI Agent API 配置
TARGET_API_URL=[REDACTED]
TARGET_API_KEY=[REDACTED] # !!! 请替换为真实 Key !!!

# 数据库配置
DB_HOST=[REDACTED]
DB_USER=[REDACTED]
DB_PASSWORD=[REDACTED] # !!! 请替换为真实密码 !!!
DB_NAME=[REDACTED]
DB_PORT=[REDACTED]
重要： 将 .env 文件添加到 .gitignore 中，避免意外提交到代码仓库。

3. 部署步骤
   3.1. 部署代码到服务器
   创建项目目录：

BASH
mkdir -p /opt/risk_api
cd /opt/risk_api
(请根据实际情况调整路径)

上传文件：
使用 scp 或其他文件传输工具将 app.py, requirements.txt, .env 文件上传到 /opt/risk_api 目录。

3.2. 创建并配置 Conda 环境
创建 Conda 环境：

BASH
# 激活 base 环境（如果需要）
# conda activate base

# 创建新环境，指定 Python 版本
conda create -n risk_env python=3.9 -y
(请根据需要调整 Python 版本)

激活环境：

BASH
conda activate risk_env
安装项目依赖：

BASH
pip install -r requirements.txt
pip install gunicorn python-dotenv # 安装 WSGI 服务器和 .env 加载库

3.3. 配置应用启动 (使用 Gunicorn + systemd)

创建 systemd 服务文件：

BASH
sudo nano /etc/systemd/system/risk_api.service
文件内容：

INI
[Unit]
Description=Gunicorn instance to serve risk_api
After=network.target

[Service]
User=your_username              # !!! 替换为运行服务的实际用户名 !!!
Group=your_group                # !!! 替换为运行服务的实际用户组 !!!
WorkingDirectory=/opt/risk_api    # !!! 替换为您的项目路径 !!!
Environment="PATH=/home/your_username/miniconda3/envs/risk_env/bin" # !!! 替换为您的 conda env bin 路径 !!!
# 使用 Unix 套接字，更安全高效
ExecStart=/home/your_username/miniconda3/envs/risk_env/bin/gunicorn --workers 4 --bind unix:/opt/risk_api/risk_api.sock app:app
# 如果需要监听 TCP 端口 (不推荐直接暴露给外部)
# ExecStart=/home/your_username/miniconda3/envs/risk_env/bin/gunicorn --workers 4 --bind 0.0.0.0:5000 app:app

[Install]
WantedBy=multi-user.target
重要：

请务必替换 User, Group, WorkingDirectory, PATH, ExecStart 中的路径和名称。
--workers 4: 可根据服务器 CPU 核心数调整。
app:app: app.py 文件名，app 是 Flask 实例名。
启动并启用服务：

BASH
sudo systemctl daemon-reload
sudo systemctl start risk_api
sudo systemctl enable risk_api
sudo systemctl status risk_api
(检查状态，确保 active (running))

3.4. 配置 Nginx 反向代理
创建 Nginx 配置文件：

BASH
sudo nano /etc/nginx/conf.d/risk_api.conf
文件内容：

NGINX
server {
    listen 80;
    server_name [REDACTED]; # !!! 替换为您的域名或服务器IP !!!

    location / {
        # 代理到 Gunicorn 的 Unix 套接字
        proxy_pass http://unix:/opt/risk_api/risk_api.sock; # !!! 确保路径与 Gunicorn 配置一致 !!!

        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_connect_timeout 60s;
        # proxy_send_timeout 60s;
        # proxy_read_timeout 60s;
    }

    # 可选：添加访问日志和错误日志配置
    access_log /var/log/nginx/risk_api_access.log;
    error_log /var/log/nginx/risk_api_error.log;
}
测试 Nginx 配置并重载：

BASH
sudo nginx -t
sudo systemctl reload nginx

4. 验证与测试
   访问 API：
   使用浏览器或 curl 访问您的服务 URL，例如：

BASH
curl http://[REDACTED]/api/overdue/history?companyName=示例公司名称
(请替换 [REDACTED] 为您的域名/IP，并提供一个有效的 companyName)

检查日志：

Gunicorn 日志： 如果使用 nohup，查看 nohup.out。如果使用 systemd，查看 sudo journalctl -u risk_api -f。
Nginx 日志： 查看 /var/log/nginx/risk_api_access.log 和 /var/log/nginx/risk_api_error.log。
Flask 应用日志： 查看 app.py 中配置的日志输出 (如果未重定向到文件，可能在 Gunicorn 日志中)。

5. 维护与监控
   服务状态检查： 定期运行 sudo systemctl status risk_api 和 sudo systemctl status nginx。
   日志监控： 关注 Gunicorn 和 Nginx 的错误日志。
   资源监控： 使用 top, htop, free -m 等命令监控服务器 CPU、内存使用情况。
   依赖更新： 定期检查并更新 requirements.txt 中的库，重新部署。
   Conda 环境维护： 避免在 base 环境中安装项目依赖，始终使用独立的 Conda 环境。

6. 回滚计划
   如果在部署后发现严重问题，可执行以下回滚操作：

停止服务：

BASH
sudo systemctl stop risk_api

恢复旧代码版本： 将之前备份的代码版本覆盖当前 /opt/risk_api 目录下的文件。
恢复旧配置： 如果修改了 Nginx 或 systemd 配置，恢复到之前的版本。
重启服务：

BASH
sudo systemctl start risk_api
sudo systemctl reload nginx

通知相关人员。

生产部署 (使用 Gunicorn)：
Flask 的内置开发服务器不适合生产环境。推荐使用 Gunicorn (一个 WSGI HTTP 服务器)。

安装 Gunicorn：

BASH
pip install gunicorn

启动 Gunicorn：
在项目目录下，确保 risk_env 已激活：

BASH

gunicorn --workers 4 --bind 0.0.0.0:5000 app:app

--workers 4: 指定工作进程数量。通常设置为 (2 * CPU核心数) + 1，但根据您的服务器资源调整。
--bind 0.0.0.0:5000: 监听所有网络接口的 5000 端口。
app:app: 指定 Flask 应用实例。第一个 app 是 Python 文件名 (app.py)，第二个 app 是 Flask 应用实例的名称（在 app = Flask(name) 中定义的）。
后台运行 Gunicorn (使用 nohup 或 systemd)：

使用 nohup (简单方式，但不推荐用于长期生产)：

BASH

nohup gunicorn --workers 4 --bind 0.0.0.0:5000 app:app &

这会将 Gunicorn 进程放到后台运行，并将日志输出到 nohup.out 文件。