lawless-design/docs/deployment-setup.md

文档站自动部署配置指南

概述

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

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

架构

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

配置步骤

1. 初始化服务器目录

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

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

2. 配置 Nginx

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

# 复制配置文件
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 证书（如未配置）

# 在服务器上执行
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. 添加并测试

手动部署

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

# 构建文档
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 - 服务器初始化脚本