# 文档站自动部署配置指南

## 概述

本文档说明如何配置 Gitea Webhook + Jenkins 实现文档站自动部署。

当代码推送到 `main` 分支且修改了文档相关文件时，会自动触发构建和部署。

## 架构

```
Git Push (main) → Gitea Webhook → Jenkins Pipeline → Build MkDocs → rsync 到服务器
```

## 配置步骤

### 1. 初始化服务器目录

```bash
# 在本地执行
./scripts/setup-docs-server.sh
```

这会在服务器上创建 `/var/www/docs.xuqinmin.com/` 目录结构。

### 2. 配置 Nginx

将 `nginx-docs.conf` 复制到服务器并重启 nginx：

```bash
# 复制配置文件
scp nginx-docs.conf root@106.54.23.149:/etc/nginx/conf.d/docs.xuqinmin.com.conf

# 测试配置
ssh root@106.54.23.149 "nginx -t"

# 重启 nginx
ssh root@106.54.23.149 "systemctl reload nginx"
```

### 3. 配置 SSL 证书（如未配置）

```bash
# 在服务器上执行
acme.sh --issue -d docs.xuqinmin.com --dns dns_dp \
  --dp-id "你的DNSPOD_ID" \
  --dp-key "你的DNSPOD_KEY"

# 安装证书
acme.sh --install-cert -d docs.xuqinmin.com \
  --key-file /opt/xuqm/acme/docs.xuqinmin.com_ecc/docs.xuqinmin.com.key \
  --fullchain-file /opt/xuqm/acme/docs.xuqinmin.com_ecc/fullchain.cer \
  --reloadcmd "systemctl reload nginx"
```

### 4. 在 Jenkins 创建 Pipeline Job

1. 访问 https://jenkins.xuqinmin.com/
2. 新建任务 → Pipeline
3. 名称: `lawless-docs-deploy`
4. 配置:
   - **Pipeline 脚本**: 从 SCM 获取 Jenkinsfile
   - **SCM**: Git
   - **仓库 URL**: `ssh://git@xuqinmin.com:2222/xuqinmin12/lawless.git`
   - **Branch**: `main`
   - **Script Path**: `Jenkinsfile`

5. 保存

### 5. 添加 Jenkins 凭据

在 Jenkins → 凭据 → 系统 → 全局凭据中添加:

1. **Gitea SSH Key** (ID: `gitea-ssh-key`)
   - 类型: SSH Username with private key
   - Username: `git`
   - Private Key: 你的 SSH 私钥

2. **Docs Server Key** (ID: `docs-server-key`)
   - 类型: SSH Username with private key
   - Username: `root`
   - Private Key: 服务器 SSH 私钥

### 6. 配置 Gitea Webhook

1. 访问 https://xuqinmin.com/xuqinmin12/lawless
2. Settings → Webhooks → Add Webhook → Gitea
3. 配置:
   - **Target URL**: `https://jenkins.xuqinmin.com/generic-webhook-trigger/invoke?token=lawless-docs-deploy`
   - **HTTP Method**: POST
   - **Content Type**: `application/json`
   - **触发事件**: Push Events
   - **Branch Filter**: `main`

4. 添加并测试

## 手动部署

如果需要手动部署，可以使用以下命令:

```bash
# 构建文档
make docs-build

# 部署到本地
make docs-deploy

# 部署到远程服务器
make docs-deploy-remote
```

## 验证

1. 访问 https://docs.xuqinmin.com/
2. 检查文档是否是最新版本
3. 查看 Jenkins 构建日志

## 故障排查

### Webhook 未触发

1. 检查 Gitea Webhook 日志 (Recent Deliveries)
2. 确认 Jenkins URL 可访问
3. 确认 token 正确

### Jenkins 构建失败

1. 检查 Jenkins 控制台输出
2. 确认凭据配置正确
3. 确认服务器 SSH 可访问

### 部署后文档未更新

1. 检查服务器目录权限
2. 检查 nginx 配置
3. 清除浏览器缓存

## 相关文件

- `Jenkinsfile` - Jenkins Pipeline 配置
- `nginx-docs.conf` - Nginx 配置
- `scripts/deploy-docs-site.sh` - 部署脚本
- `scripts/setup-docs-server.sh` - 服务器初始化脚本