第3章报送环境搭建

3、报送环境搭建：Python环境配置、数据库连接（Oracle/MySQL）、调度工具（Airflow/Crontab）、版本控制（Git）

说实话，金融监管报送这事儿，最怕的不是业务逻辑复杂，而是环境没搭好。

我见过太多团队，代码写得漂漂亮亮，结果一上线就崩——Python版本不对、连不上数据库、调度任务没跑起来、代码版本乱成一锅粥。嗯，这些坑我都踩过。今天咱们就把这套环境彻底捋一遍。

3.1 Python环境配置：别让版本坑了你

我个人习惯，每个项目都建独立的虚拟环境。为什么？因为金融项目依赖的库版本太敏感了。比如pandas 1.3和2.0在某些API上不兼容，你想想看，要是两个项目共用一套环境，改一个就炸另一个。

  核心原则： 永远不要用系统自带的Python跑生产项目。用虚拟环境隔离。

3.1.1 安装Python（推荐3.9+）

我建议直接用pyenv管理多版本。尤其是你要对接不同监管机构的系统时，有的老系统只支持Python 3.7，有的要求3.10。pyenv一键切换，省心。

# 安装pyenv（macOS/Linux）
curl https://pyenv.run | bash

# 安装指定版本
pyenv install 3.9.18

# 设置全局版本
pyenv global 3.9.18

# 验证
python --version

避坑指南： 我曾经在Windows上直接装Python 3.11，结果有个监管报送库死活装不上。后来发现是C++编译工具链的问题。建议Windows用户用Anaconda或者直接装Python 3.9，兼容性最好。

3.1.2 创建虚拟环境

说白了，虚拟环境就是给每个项目一个独立的小房间。你在这个房间里装什么库，都不会影响到别的房间。

# 创建虚拟环境
python -m venv venv_report

# 激活（Windows）
venv_report\Scripts\activate

# 激活（macOS/Linux）
source venv_report/bin/activate

# 安装常用库
pip install pandas numpy openpyxl cx_Oracle pymysql sqlalchemy

记得把依赖导出到requirements.txt。这样别人拉下代码，直接pip install -r requirements.txt就能复现你的环境。

pip freeze > requirements.txt

3.2 数据库连接：Oracle和MySQL的实战配置

金融监管报送，数据源基本就是Oracle和MySQL。我遇到过最头疼的事——连不上数据库，结果查了半天，是驱动版本不对。

3.2.1 连接Oracle

Oracle的坑比较多。首先你要装Oracle Instant Client，然后配置环境变量。嗯，这一步很多人会忘。

# 安装cx_Oracle
pip install cx_Oracle

# 配置环境变量（Windows）
# 把instantclient_19_8的路径加到PATH里

# 配置环境变量（Linux）
export LD_LIBRARY_PATH=/opt/oracle/instantclient_19_8:$LD_LIBRARY_PATH

连接代码示例：

import cx_Oracle

# 连接字符串格式：用户名/密码@主机:端口/服务名
conn = cx_Oracle.connect(
    "report_user/report_pass@192.168.1.100:1521/ORCLPDB"
)

cursor = conn.cursor()
cursor.execute("SELECT * FROM v$version")
for row in cursor:
    print(row)

cursor.close()
conn.close()

注意： 我曾经在生产环境遇到过字符集问题。Oracle的NLS_LANG设置不对，中文全变成乱码。建议统一设置为：export NLS_LANG=AMERICAN_AMERICA.AL32UTF8

3.2.2 连接MySQL

MySQL相对简单，但也要注意SSL连接的问题。尤其是监管报送，很多银行要求加密传输。

# 安装pymysql
pip install pymysql

# 或者用mysql-connector-python
pip install mysql-connector-python

import pymysql

conn = pymysql.connect(
    host="192.168.1.101",
    port=3306,
    user="report_user",
    password="report_pass",
    database="report_db",
    charset="utf8mb4",
    # 如果要求SSL连接
    ssl={"ca": "/path/to/ca-cert.pem"}
)

cursor = conn.cursor()
cursor.execute("SHOW TABLES")
for table in cursor:
    print(table)

cursor.close()
conn.close()

小技巧： 我建议用SQLAlchemy做ORM层。这样切换数据库时，只需要改连接字符串，代码基本不用动。尤其是监管报送，经常要同时从Oracle和MySQL取数，SQLAlchemy的方言机制能帮你省很多事。

3.3 调度工具：Airflow vs Crontab

监管报送最怕什么？漏报、迟报。所以调度工具是命脉。我两种都用过，说说我的感受。

3.3.1 Crontab：简单粗暴，适合小项目

如果你就一两个报送任务，Crontab足够了。但要注意日志和异常处理。

# 每天凌晨2点执行报送脚本
0 2 * * * /path/to/venv/bin/python /path/to/report_script.py >> /var/log/report.log 2>&1

# 每月1号凌晨3点执行月报
0 3 1 * * /path/to/venv/bin/python /path/to/monthly_report.py

我曾经踩过的坑： Crontab的环境变量和终端不一样。你在终端能跑的脚本，放到Crontab里可能报错。解决方案：在脚本开头显式设置PATH和PYTHONPATH。

3.3.2 Airflow：企业级调度，适合复杂场景

说实话，一旦报送任务超过5个，或者有依赖关系（比如日报跑完才能跑月报），Crontab就力不从心了。这时候Airflow是更好的选择。

安装和初始化：

# 安装Airflow
pip install apache-airflow

# 初始化数据库
airflow db init

# 创建管理员用户
airflow users create \
    --username admin \
    --firstname Admin \
    --lastname User \
    --role Admin \
    --email admin@example.com

# 启动web服务（默认端口8080）
airflow webserver --port 8080

# 启动调度器
airflow scheduler

一个简单的报送DAG示例：

from airflow import DAG
from airflow.operators.python import PythonOperator
from datetime import datetime, timedelta

default_args = {
    'owner': 'report_team',
    'depends_on_past': False,
    'email_on_failure': True,
    'email_on_retry': False,
    'retries': 3,
    'retry_delay': timedelta(minutes=5),
}

dag = DAG(
    'daily_regulatory_report',
    default_args=default_args,
    description='每日监管报送任务',
    schedule_interval='0 2 * * *',  # 每天凌晨2点
    start_date=datetime(2024, 1, 1),
    catchup=False,
)

def extract_data():
    # 从Oracle取数
    pass

def transform_data():
    # 数据转换
    pass

def load_to_regulatory():
    # 报送监管系统
    pass

t1 = PythonOperator(
    task_id='extract',
    python_callable=extract_data,
    dag=dag
)

t2 = PythonOperator(
    task_id='transform',
    python_callable=transform_data,
    dag=dag
)

t3 = PythonOperator(
    task_id='load',
    python_callable=load_to_regulatory,
    dag=dag
)

t1 >> t2 >> t3

  我的建议： 如果团队规模小，先上Crontab快速跑起来。等任务多了再迁移到Airflow。别一开始就上重器，容易把自己搞晕。

3.4 版本控制：Git是底线

这个我真不想多说——没有Git的报送项目，就是定时炸弹。我见过有人用「日报_最终版_20240101.py」这种命名方式，结果某天改错了，想回退都找不到版本。

3.4.1 基本配置

# 配置用户信息
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

# 初始化仓库
cd /path/to/report_project
git init

# 创建.gitignore，排除敏感文件和虚拟环境
echo "venv/" >> .gitignore
echo "*.pyc" >> .gitignore
echo "__pycache__/" >> .gitignore
echo "config.ini" >> .gitignore  # 数据库密码等敏感信息

3.4.2 分支策略

我建议用简单的Git Flow：

main分支： 只放生产可用的代码。每次报送成功后，合并到这里。
dev分支： 日常开发用。大家往这里合并。
feature分支： 每个新功能或修改，从dev拉一个feature分支。比如feature/新增银保监报送格式。

# 创建并切换到dev分支
git checkout -b dev

# 从dev拉取feature分支
git checkout -b feature/新增银保监报送格式

# 开发完成后合并回dev
git checkout dev
git merge feature/新增银保监报送格式

# 测试通过后合并到main
git checkout main
git merge dev
git tag v1.2.0  # 打标签，方便回退

避坑指南： 我曾经犯过一个错——把数据库密码直接提交到了Git仓库。后来虽然删了，但历史记录里还有。正确的做法是用环境变量或者配置文件，然后把配置文件加到.gitignore里。

3.5 整体架构图

下面这张图，是我做监管报送项目时常用的环境架构。说白了，就是数据从源库取出来，经过Python处理，然后调度工具定时触发，最后用Git管住所有代码。

3.6 环境验证清单

每次搭建完环境，我都会跑一遍这个清单。别嫌麻烦，真出问题的时候，能省你半天时间。

检查项	验证方法	预期结果
Python版本	`python --version`	3.9.x 或 3.10.x
虚拟环境	`pip list`	只包含本项目依赖
Oracle连接	运行cx_Oracle连接测试	成功返回数据库版本
MySQL连接	运行pymysql连接测试	成功返回表列表
Airflow	访问 http://localhost:8080	能看到Airflow UI
Git	`git status`	显示干净的工作区

最后提醒一句： 环境搭建不是一次性工作。每次升级Python版本、换数据库驱动、改调度配置，都要重新验证一遍。我见过太多人「搭好就没管过」，结果某天系统升级后，报送直接挂了。

好了，环境搭好了，下一步就是写真正的报送逻辑了。记住，环境稳了，后面的事就顺了。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

3、报送环境搭建：Python环境配置、数据库连接（Oracle/MySQL）、调度工具（Airflow/Crontab）、版本控制（Git）

3.1 Python环境配置：别让版本坑了你

3.1.1 安装Python（推荐3.9+）

3.1.2 创建虚拟环境

3.2 数据库连接：Oracle和MySQL的实战配置

3.2.1 连接Oracle

3.2.2 连接MySQL

3.3 调度工具：Airflow vs Crontab

3.3.1 Crontab：简单粗暴，适合小项目

3.3.2 Airflow：企业级调度，适合复杂场景

3.4 版本控制：Git是底线

3.4.1 基本配置

3.4.2 分支策略

3.5 整体架构图

3.6 环境验证清单