折扣卡CPS私有化部署源码部署教程
折扣卡CPS私有化部署，是将整套卡密管理、小程序权益、CPS渠道适配器、分佣结算、订单追踪源码部署到自有服务器，数据自主存储、接口自主对接联盟渠道，适合代理商、服务商独立运营。很多部署过程容易出现数据库字符集错误、CPS回调不通、MQ连接失败、分佣模板不生效、小程序域名校验失败等问题。本文从环境准备、源码编译、数据库初始化、配置修改、服务启动、Nginx反向代理、小程序配置、上线校验、运维备份完整讲解，附带后端配置示例代码。
痛点分析
第一，环境版本不匹配，JDK、MySQL、Redis版本不对，启动直接报错，CPS异步消息消费异常。
第二，配置文件直接使用开发环境参数，联盟密钥、微信小程序AppID、数据库明文直接提交，存在泄露风险。
第三，忽略CPS统一回调地址配置，第三方联盟回调无法到达服务，订单收不到、没有佣金。
第四，RocketMQ或者Redis外网没有放行，归因快照、链路追踪缓存失效，大量订单归因丢失。
第五，没有区分测试环境和生产环境配置，上线后调试日志过多，性能差，资金流水日志没有隔离。
第六，缺少systemd托管，用nohup简单启动，服务器重启后服务不会自动拉起，CPS对账定时任务中断。
第七，私有化部署之后没有定期备份脚本，数据库误操作、磁盘故障导致卡密、分佣订单数据丢失。
整体部署架构说明
整套源码为SpringBoot后端 + Vue管理后台 + 微信小程序前端。后端包含卡密模块、用户卡包、CPS渠道适配器、分佣结算、链路追踪、定时对账任务；依赖MySQL存储业务数据、Redis做缓存与归因快照、RocketMQ处理订单异步消息；Nginx承载静态资源、HTTPS证书、反向代理API与CPS回调接口。
部署分两种方案：原生Linux部署、Docker Compose容器化部署，教程优先原生部署，稳定性更适合私有化长期运营。
环境准备
服务器推荐CentOS7/CentOS8、Ubuntu 20.04，最低配置2核4G，生产推荐4核8G，SSD磁盘。
依赖清单：
JDK 1.8 / OpenJDK 11，SpringBoot2.7版本；
MySQL 8.0，字符集utf8mb4；
Redis 6.0+；
RocketMQ 4.9.x（可选，小型私有化可替换Redis消息队列）；
Maven 3.6+；
Nginx 1.20+；
域名与SSL证书，小程序业务必须HTTPS；
微信小程序AppID、AppSecret；各个CPS联盟渠道的Key、Secret、推广PID。
服务器安全组放行端口：80、443、8080、6379、3306、9876（RocketMQ）。数据库、Redis不要直接开放公网访问，仅内网通信。
源码拉取与编译打包
把源码上传服务器或者服务器直接git拉取源码仓库。
后端打包命令：
mvn clean package -Dmaven.test.skip=true -Pprod-Pprod代表读取生产配置，打包完成后target目录生成jar包，例如 cps-discount-card.jar。
Vue管理后台打包：
npm install npm run build:prod打包产物dist目录，后续上传到Nginx静态目录。
小程序端源码在开发者工具内修改后端接口域名之后上传提交审核。
数据库初始化
登录MySQL，创建独立业务库，字符集utf8mb4，支持emoji：
CREATEDATABASEcps_discountDEFAULTCHARACTERSETutf8mb4COLLATEutf8mb4_unicode_ci;导入项目根目录sql文件夹内初始化脚本，包含卡密表、用户卡包、CPS订单、分佣明细、链路事件、账户流水表。
导入完成后执行基础权限账号配置，禁止root账号给业务程序使用，新建独立数据库账号。
生产配置文件修改
找到application-prod.yml，修改数据库、Redis、MQ、小程序、CPS渠道参数，不要修改application.yml公共配置。
示例配置片段：
spring:datasource:url:jdbc:mysql://127.0.0.1:3306/cps_discount?useUnicode=true&characterEncoding=utf8mb4&serverTimezone=Asia/Shanghai&allowMultiQueries=trueusername:cps_userpassword:DB@Pass123456redis:host:127.0.0.1port:6379password:Redis@654321rocketmq:name-server:127.0.0.1:9876producer-group:cps-prod-groupcps:# CPS统一回调域名，联盟后台填写这个地址callback-domain:[https://api.xxx.com/cps/unified/callback](https://api.xxx.com/cps/unified/callback)wx:mini-app-id:wx123456789abcdefmini-app-secret:小程序密钥配置重点：cps.callback-domain是第三方联盟回调地址，联盟平台后台必须填写这个地址，否则订单无法推送进来。
分佣模板、渠道配置在后台可视化页面新增，不需要写在配置文件内。
后端服务托管配置（systemd）
新建服务文件 /etc/systemd/system/cps-card.service
[Unit] Description=CPS折扣卡私有化后端服务 After=network.target [Service] User=www WorkingDirectory=/data/cps ExecStart=/usr/local/jdk/bin/java -jar cps-discount-card.jar --spring.profiles.active=prod SuccessExitStatus=143 Restart=always RestartSec=5 [Install] WantedBy=multi-user.target执行命令加载并设置开机自启：
systemctl daemon-reload systemctl enable cps-card systemctl start cps-card systemctl status cps-card查看日志：journalctl -u cps-card -f，启动无报错代表后端服务正常运行。
Nginx配置（管理后台 + API + CPS回调）
Nginx配置示例，同时托管管理后台静态资源，反向代理后端接口和CPS回调：
server { listen 443 ssl; server_name api.xxx.com; ssl_certificate cert/api.xxx.com.pem; ssl_certificate_key cert/api.xxx.com.key; location /admin { root /data/www; index index.html; try_files $uri $uri/ /admin/index.html; } location / { proxy_pass [http://127.0.0.1:8080](http://127.0.0.1:8080); 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; } }重载Nginx：nginx -t && nginx -s reload。
CPS回调接口地址：https://api.xxx.com/cps/unified/callback，复制这个地址填写到各个CPS联盟后台回调配置中。
微信小程序配置
小程序后台设置服务器域名，request合法域名填入api.xxx.com；
小程序源码修改request请求基地址，指向私有化API域名；
测试流程：小程序登录、兑换激活卡密、进入CPS专区生成跳转链接，后端返回带sid追踪的跳转地址。
这里要注意，小程序业务域名需要提前配置，否则跳转第三方CPS页面会被拦截。
上线校验流程
第一步，访问后台地址，登录管理员账号，检查租户配置、CPS渠道配置、分佣模板是否正常新增；
第二步，新增卡密批次，开启CPS联动，生成一批测试卡密；
第三步，小程序激活测试卡，调用转链接口，检查Redis里面是否生成sid归因快照；
第四步，在联盟平台测试下单，查看回调日志，校验订单入库、归因匹配、分佣明细是否生成；
第五步，模拟退款订单，校验逆向扣佣流水、账户余额扣减逻辑；
第六步，查看定时对账任务，核对联盟报表拉取、订单解冻功能。
运维、备份与安全策略
定时备份脚本，每日凌晨备份数据库，压缩上传备份目录，保留7天备份：
mysqldump-ucps_user-pDB@Pass123456 cps_discount>/data/backup/cps_$(date+%Y%m%d).sql安全要点：
- 不要把配置文件密钥提交到代码仓库，生产配置单独隔离；
- 关闭MySQL、Redis公网访问，使用内网通信；
- 定期更新服务器系统补丁；
- 日志按天分卷，清理过期链路追踪日志，避免磁盘打满；
- 私有化部署资金模块，建议开启操作日志，所有提现、分佣变更留痕。
常见部署故障排查
- 联盟回调404：核对Nginx代理路径、后端接口路径，确认联盟回调地址填写正确；
- 订单收到但是不分佣：检查卡密批次CPS联动开关、分佣模板是否启用、归因信息是否正常写入；
- MQ消费失败：检查RocketMQ NameServer连通性、topic是否提前创建；
- 小程序502：后端服务宕机，systemctl status cps-card查看服务状态；
- 中文乱码：确认MySQL连接串带上utf8mb4参数，数据库排序规则正确。
总结
折扣卡CPS私有化源码部署核心是环境版本对齐、生产配置隔离、回调地址闭环、服务托管自启动、数据库定期备份。私有化部署之后，卡密、用户权益、CPS订单、分佣资金数据全部自持，适合独立运营、多代理商招募的业务模式。整套服务和之前CPS适配器、卡密联动、分佣结算、订单链路追踪模块完全兼容，部署完成后可以直接开启渠道对接、卡密分发、用户返利运营。
