# 证书管理系统部署指南

本文档详细说明了如何部署和使用证书管理系统。

## 系统概述

证书管理系统支持多环境部署，能够自动处理微信支付和支付宝的证书加载：

- **开发环境**: 从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. 验证证书状态

### 定期检查

- 每月检查证书有效期
- 监控证书健康状态
- 更新过期证书
- 备份证书文件

## 支持和联系

如有问题，请联系技术支持或查看项目文档。