273 lines
5.6 KiB
Markdown
273 lines
5.6 KiB
Markdown
# 证书管理系统部署指南
|
||
|
||
本文档详细说明了如何部署和使用证书管理系统。
|
||
|
||
## 系统概述
|
||
|
||
证书管理系统支持多环境部署，能够自动处理微信支付和支付宝的证书加载：
|
||
|
||
- **开发环境**: 从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. 验证证书状态
|
||
|
||
### 定期检查
|
||
|
||
- 每月检查证书有效期
|
||
- 监控证书健康状态
|
||
- 更新过期证书
|
||
- 备份证书文件
|
||
|
||
## 支持和联系
|
||
|
||
如有问题，请联系技术支持或查看项目文档。
|