144 行
3.3 KiB
Markdown
144 行
3.3 KiB
Markdown
# 文档站自动部署配置指南
|
||
|
||
## 概述
|
||
|
||
本文档说明如何配置 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` - 服务器初始化脚本
|
