改造支付证书管理模块
This commit is contained in:
272
docs/CERTIFICATE_DEPLOYMENT.md
Normal file
272
docs/CERTIFICATE_DEPLOYMENT.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# 证书管理系统部署指南
|
||||
|
||||
本文档详细说明了如何部署和使用证书管理系统。
|
||||
|
||||
## 系统概述
|
||||
|
||||
证书管理系统支持多环境部署，能够自动处理微信支付和支付宝的证书加载：
|
||||
|
||||
- **开发环境**: 从classpath加载证书
|
||||
- **生产环境**: 从Docker挂载卷加载证书
|
||||
- **文件系统模式**: 从本地文件系统加载证书
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
项目根目录/
|
||||
├── certs/ # 生产环境证书目录
|
||||
│ ├── README.md # 证书目录说明
|
||||
│ ├── wechat/ # 微信支付证书
|
||||
│ │ ├── apiclient_key.pem # 商户私钥证书
|
||||
│ │ ├── apiclient_cert.pem # 商户证书
|
||||
│ │ └── wechatpay_cert.pem # 微信支付平台证书
|
||||
│ └── alipay/ # 支付宝证书
|
||||
│ ├── app_private_key.pem # 应用私钥
|
||||
│ ├── appCertPublicKey.crt # 应用公钥证书
|
||||
│ ├── alipayCertPublicKey.crt # 支付宝公钥证书
|
||||
│ └── alipayRootCert.crt # 支付宝根证书
|
||||
├── src/main/resources/certs/dev/ # 开发环境证书目录
|
||||
│ ├── wechat/ # 微信支付证书
|
||||
│ └── alipay/ # 支付宝证书
|
||||
├── scripts/
|
||||
│ └── setup-certificates.sh # 证书管理脚本
|
||||
├── Dockerfile # Docker构建文件
|
||||
└── docker-compose.yml # Docker编排文件
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 初始化证书目录
|
||||
|
||||
```bash
|
||||
# 使用脚本初始化
|
||||
./scripts/setup-certificates.sh init
|
||||
|
||||
# 或手动创建
|
||||
mkdir -p certs/wechat certs/alipay
|
||||
mkdir -p src/main/resources/certs/dev/wechat
|
||||
mkdir -p src/main/resources/certs/dev/alipay
|
||||
```
|
||||
|
||||
### 2. 配置证书文件
|
||||
|
||||
#### 开发环境
|
||||
将证书文件放置在 `src/main/resources/certs/dev/` 目录下：
|
||||
|
||||
```bash
|
||||
# 微信支付证书
|
||||
cp your-wechat-certs/* src/main/resources/certs/dev/wechat/
|
||||
|
||||
# 支付宝证书
|
||||
cp your-alipay-certs/* src/main/resources/certs/dev/alipay/
|
||||
```
|
||||
|
||||
#### 生产环境
|
||||
将证书文件放置在 `certs/` 目录下：
|
||||
|
||||
```bash
|
||||
# 微信支付证书
|
||||
cp your-wechat-certs/* certs/wechat/
|
||||
|
||||
# 支付宝证书
|
||||
cp your-alipay-certs/* certs/alipay/
|
||||
```
|
||||
|
||||
### 3. 设置证书权限
|
||||
|
||||
```bash
|
||||
# 使用脚本设置权限
|
||||
./scripts/setup-certificates.sh perms
|
||||
|
||||
# 或手动设置
|
||||
chmod -R 444 certs/
|
||||
chmod 755 certs/ certs/wechat/ certs/alipay/
|
||||
```
|
||||
|
||||
### 4. 验证证书配置
|
||||
|
||||
```bash
|
||||
# 检查证书文件
|
||||
./scripts/setup-certificates.sh check
|
||||
```
|
||||
|
||||
## 环境配置
|
||||
|
||||
### 开发环境 (application.yml)
|
||||
|
||||
```yaml
|
||||
certificate:
|
||||
load-mode: CLASSPATH
|
||||
dev-cert-path: certs/dev
|
||||
```
|
||||
|
||||
### 生产环境 (application-prod.yml)
|
||||
|
||||
```yaml
|
||||
certificate:
|
||||
load-mode: VOLUME
|
||||
cert-root-path: /app/certs
|
||||
```
|
||||
|
||||
## Docker部署
|
||||
|
||||
### 1. 构建镜像
|
||||
|
||||
```bash
|
||||
# 构建应用
|
||||
mvn clean package -DskipTests
|
||||
|
||||
# 构建Docker镜像
|
||||
docker build -t gxwebsoft-server .
|
||||
```
|
||||
|
||||
### 2. 使用Docker Compose部署
|
||||
|
||||
```bash
|
||||
# 启动所有服务
|
||||
docker-compose up -d
|
||||
|
||||
# 查看日志
|
||||
docker-compose logs -f gxwebsoft-app
|
||||
|
||||
# 停止服务
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### 3. 单独运行容器
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name gxwebsoft-server \
|
||||
-p 8080:8080 \
|
||||
-v $(pwd)/certs:/app/certs:ro \
|
||||
-e SPRING_PROFILES_ACTIVE=prod \
|
||||
-e CERTIFICATE_LOAD_MODE=VOLUME \
|
||||
gxwebsoft-server
|
||||
```
|
||||
|
||||
## API接口
|
||||
|
||||
证书管理系统提供了完整的REST API：
|
||||
|
||||
### 获取证书状态
|
||||
```http
|
||||
GET /api/system/certificate/status
|
||||
```
|
||||
|
||||
### 证书健康检查
|
||||
```http
|
||||
GET /api/system/certificate/health
|
||||
```
|
||||
|
||||
### 获取诊断信息
|
||||
```http
|
||||
GET /api/system/certificate/diagnostic
|
||||
```
|
||||
|
||||
### 检查特定证书
|
||||
```http
|
||||
GET /api/system/certificate/check/{certType}/{fileName}
|
||||
```
|
||||
|
||||
### 验证证书文件
|
||||
```http
|
||||
GET /api/system/certificate/validate/{certType}/{fileName}
|
||||
```
|
||||
|
||||
## 监控和健康检查
|
||||
|
||||
### Spring Boot Actuator
|
||||
|
||||
系统集成了Spring Boot Actuator健康检查：
|
||||
|
||||
```http
|
||||
GET /actuator/health
|
||||
```
|
||||
|
||||
健康检查会验证：
|
||||
- 证书文件是否存在
|
||||
- 证书文件是否可读
|
||||
- X509证书是否有效
|
||||
- 证书是否过期
|
||||
|
||||
### 日志监控
|
||||
|
||||
关键日志信息：
|
||||
- 证书加载模式
|
||||
- 证书文件路径
|
||||
- 证书验证结果
|
||||
- 错误和异常信息
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **证书文件不存在**
|
||||
```
|
||||
检查文件路径和权限
|
||||
使用 ./scripts/setup-certificates.sh check 验证
|
||||
```
|
||||
|
||||
2. **证书权限错误**
|
||||
```
|
||||
使用 ./scripts/setup-certificates.sh perms 修复权限
|
||||
```
|
||||
|
||||
3. **Docker挂载问题**
|
||||
```
|
||||
确保证书目录正确挂载到 /app/certs
|
||||
检查文件权限和SELinux设置
|
||||
```
|
||||
|
||||
4. **证书过期**
|
||||
```
|
||||
使用 /api/system/certificate/validate 接口检查证书有效期
|
||||
及时更新过期证书
|
||||
```
|
||||
|
||||
### 调试命令
|
||||
|
||||
```bash
|
||||
# 检查证书文件
|
||||
./scripts/setup-certificates.sh check
|
||||
|
||||
# 验证Docker挂载
|
||||
docker exec -it gxwebsoft-server ls -la /app/certs
|
||||
|
||||
# 查看应用日志
|
||||
docker-compose logs -f gxwebsoft-app
|
||||
|
||||
# 测试证书API
|
||||
curl -X GET "http://localhost:8080/api/system/certificate/health"
|
||||
```
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
1. **不要将证书文件提交到版本控制系统**
|
||||
2. **设置正确的文件权限（444 for files, 755 for directories）**
|
||||
3. **定期更新证书文件**
|
||||
4. **备份重要的证书文件**
|
||||
5. **使用HTTPS传输证书文件**
|
||||
6. **限制证书文件的访问权限**
|
||||
|
||||
## 维护和更新
|
||||
|
||||
### 证书更新流程
|
||||
|
||||
1. 备份现有证书
|
||||
2. 下载新证书文件
|
||||
3. 更新证书文件
|
||||
4. 重启应用服务
|
||||
5. 验证证书状态
|
||||
|
||||
### 定期检查
|
||||
|
||||
- 每月检查证书有效期
|
||||
- 监控证书健康状态
|
||||
- 更新过期证书
|
||||
- 备份证书文件
|
||||
|
||||
## 支持和联系
|
||||
|
||||
如有问题，请联系技术支持或查看项目文档。
|
||||
Reference in New Issue
Block a user