kknongchang_2506/app/Module/Transfer/Docs/DEPLOYMENT.md

Transfer模块部署文档

部署概述

Transfer模块是一个完整的资金划转解决方案，支持农场内部模式和外部API模式。本文档详细说明了模块的部署、配置和维护流程。

系统要求

基础环境

• PHP >= 8.1
• Laravel >= 9.0
• MySQL >= 8.0
• Redis >= 6.0（用于队列和缓存）

扩展要求

• BCMath扩展（高精度数学计算）
• cURL扩展（外部API调用）
• JSON扩展（数据序列化）

依赖模块

• Fund模块（资金管理）
• OpenAPI模块（对外接口，可选）

部署步骤

1. 数据库部署

1.1 执行建表SQL

# 连接到MySQL数据库
mysql -u username -p database_name

# 执行建表SQL
source app/Module/Transfer/Database/transfer_tables.sql

1.2 执行初始化数据

# 执行初始化数据SQL
source app/Module/Transfer/Database/transfer_init_data.sql

1.3 创建性能索引

# 执行性能优化SQL
source app/Module/Transfer/Database/optimization.sql

2. 配置文件部署

2.1 发布配置文件

# 发布Transfer配置文件
php artisan vendor:publish --tag=transfer-config

2.2 配置环境变量

在 .env 文件中添加：

# Transfer模块配置
TRANSFER_DEBUG=false
TRANSFER_API_TIMEOUT=30
TRANSFER_QUEUE_CONNECTION=redis
TRANSFER_CACHE_DRIVER=redis

2.3 修改配置文件

编辑 config/transfer.php：

// 根据生产环境需求调整配置
'api' => [
    'timeout' => env('TRANSFER_API_TIMEOUT', 30),
    'retry_times' => 3,
],

'queue' => [
    'default' => env('TRANSFER_QUEUE_CONNECTION', 'redis'),
],

3. 队列配置

3.1 配置队列驱动

在 config/queue.php 中确保Redis配置正确：

'connections' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => 'default',
        'queue' => env('REDIS_QUEUE', 'default'),
        'retry_after' => 90,
        'block_for' => null,
    ],
],

3.2 启动队列工作进程

# 启动Transfer队列工作进程
php artisan queue:work redis --queue=transfer,transfer_callback --sleep=3 --tries=3 --max-time=3600

# 使用Supervisor管理队列进程（推荐）
# 创建 /etc/supervisor/conf.d/transfer-worker.conf

Supervisor配置示例：

[program:transfer-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/artisan queue:work redis --queue=transfer,transfer_callback --sleep=3 --tries=3 --max-time=3600
directory=/path/to/project
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/transfer-worker.log
stopwaitsecs=3600

4. 定时任务配置

4.1 添加Cron任务

# 编辑crontab
crontab -e

# 添加以下任务
# Transfer订单处理（每5分钟）
*/5 * * * * cd /path/to/project && php artisan transfer:process --type=orders --limit=100 >> /dev/null 2>&1

# Transfer回调处理（每2分钟）
*/2 * * * * cd /path/to/project && php artisan transfer:process --type=callbacks --limit=50 >> /dev/null 2>&1

# 每日统计报告（每天凌晨1点）
0 1 * * * cd /path/to/project && php artisan transfer:stats --period=yesterday --export=/var/log/transfer-daily-stats.csv >> /dev/null 2>&1

5. 权限配置

5.1 文件权限

# 设置正确的文件权限
chown -R www-data:www-data /path/to/project/storage
chown -R www-data:www-data /path/to/project/bootstrap/cache
chmod -R 755 /path/to/project/storage
chmod -R 755 /path/to/project/bootstrap/cache

5.2 日志目录权限

# 创建Transfer日志目录
mkdir -p /var/log/transfer
chown www-data:www-data /var/log/transfer
chmod 755 /var/log/transfer

配置说明

1. 应用配置

1.1 农场内部模式

适用于纯内部资金流转，无需外部API：

// 所有API URL留空即为农场内部模式
'order_callback_url' => null,
'order_in_info_url' => null,
'order_out_create_url' => null,
'order_out_info_url' => null,

1.2 外部API模式

适用于与外部系统对接：

// 配置相应的API端点
'order_callback_url' => 'https://external-api.com/callback',
'order_out_create_url' => 'https://external-api.com/transfer/create',
'order_out_info_url' => 'https://external-api.com/transfer/info',

2. 安全配置

2.1 API签名验证

'security' => [
    'signature_verification' => true,
    'signature_method' => 'md5',
],

2.2 IP白名单（可选）

'security' => [
    'ip_whitelist_enabled' => true,
    'ip_whitelist' => [
        '192.168.1.100',
        '10.0.0.50',
    ],
],

3. 性能配置

3.1 缓存配置

'cache' => [
    'enabled' => true,
    'app_config_ttl' => 3600,
    'stats_ttl' => 300,
],

3.2 队列配置

'queue' => [
    'max_tries' => 3,
    'timeout' => 120,
    'failed_job_retention' => 86400,
],

监控和维护

1. 日志监控

1.1 应用日志

# 查看Transfer模块日志
tail -f storage/logs/laravel.log | grep Transfer

# 查看队列日志
tail -f /var/log/transfer-worker.log

1.2 数据库日志

# 查看慢查询日志
tail -f /var/log/mysql/slow.log | grep transfer

2. 性能监控

2.1 队列监控

# 查看队列状态
php artisan queue:monitor redis:transfer,redis:transfer_callback

# 查看失败任务
php artisan queue:failed

2.2 数据库监控

-- 查看表大小
SELECT 
    TABLE_NAME,
    ROUND(((DATA_LENGTH + INDEX_LENGTH) / 1024 / 1024), 2) AS 'Size (MB)',
    TABLE_ROWS
FROM information_schema.TABLES 
WHERE TABLE_NAME LIKE 'kku_transfer_%';

-- 查看索引使用情况
SHOW INDEX FROM kku_transfer_orders;

3. 健康检查

3.1 创建健康检查脚本

#!/bin/bash
# transfer-health-check.sh

# 检查数据库连接
php artisan tinker --execute="DB::connection()->getPdo();"

# 检查队列工作进程
ps aux | grep "queue:work" | grep -v grep

# 检查Redis连接
redis-cli ping

# 检查最近的订单处理情况
php artisan transfer:stats --period=today

3.2 设置监控告警

# 添加到crontab，每10分钟检查一次
*/10 * * * * /path/to/transfer-health-check.sh || echo "Transfer health check failed" | mail -s "Transfer Alert" admin@example.com

故障排除

1. 常见问题

1.1 队列任务失败

# 查看失败任务详情
php artisan queue:failed

# 重试失败任务
php artisan queue:retry all

# 清除失败任务
php artisan queue:flush

1.2 外部API调用失败

# 检查网络连接
curl -I https://external-api.com/health

# 查看API调用日志
grep "ExternalApiService" storage/logs/laravel.log

1.3 数据库性能问题

-- 查看正在执行的查询
SHOW PROCESSLIST;

-- 查看锁等待情况
SELECT * FROM information_schema.INNODB_LOCKS;

-- 优化表
OPTIMIZE TABLE kku_transfer_orders;

2. 紧急恢复

2.1 数据备份恢复

# 恢复数据库备份
mysql -u username -p database_name < transfer_backup.sql

2.2 服务重启

# 重启队列工作进程
supervisorctl restart transfer-worker:*

# 重启Web服务
systemctl restart nginx
systemctl restart php8.1-fpm

升级指南

1. 版本升级步骤

1. 备份数据库和配置文件
2. 停止队列工作进程
3. 更新代码
4. 执行数据库迁移（如有）
5. 更新配置文件
6. 重启服务
7. 验证功能正常

2. 兼容性检查

• 检查PHP版本兼容性
• 检查依赖模块版本
• 验证API接口兼容性
• 测试核心功能

安全建议

1. 定期更新密钥：定期更换API签名密钥
2. 访问控制：限制后台管理访问IP
3. 数据加密：敏感数据传输使用HTTPS
4. 审计日志：保留详细的操作日志
5. 权限最小化：数据库用户权限最小化

联系支持

如遇到部署问题，请联系技术支持团队，并提供：

• 错误日志
• 系统环境信息
• 配置文件内容
• 问题复现步骤