From 8aba243ec04ca12f5467c57febaf5f9e9b9acf02 Mon Sep 17 00:00:00 2001
From: FXY <fxy@beast-trader.local>
Date: Fri, 12 Jun 2026 20:56:08 +0800
Subject: [PATCH] docs: add Caddy reverse proxy reference (replaces Lucky)

---
 docs/guides/caddy_reference.md | 73 ++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 docs/guides/caddy_reference.md

diff --git a/docs/guides/caddy_reference.md b/docs/guides/caddy_reference.md
new file mode 100644
index 0000000..ecd7353
--- /dev/null
+++ b/docs/guides/caddy_reference.md
@@ -0,0 +1,73 @@
+# Caddy 反向代理 — 操作参考
+
+> 部署：2026-06-12 | 替代：Lucky
+
+## 配置文件
+
+```
+路径: /etc/caddy/Caddyfile
+编辑后: sudo caddy fmt --overwrite /etc/caddy/Caddyfile
+重载: sudo systemctl restart caddy
+```
+
+## 当前管理的域名
+
+```
+www.xybkwd.top, xybkwd.top  →  localhost:8090 (Halo 博客)
+gitea.xybkwd.top             →  localhost:3000 (Gitea)
+dashboard.xybkwd.top         →  localhost:9000 (Beast Trader Dashboard)
+```
+
+## 常用命令
+
+```bash
+# 查看状态
+sudo systemctl status caddy
+
+# 查看日志
+sudo journalctl -u caddy -n 50 --no-pager
+
+# 实时日志
+sudo journalctl -u caddy -f
+
+# 重启
+sudo systemctl restart caddy
+
+# 测试配置
+sudo caddy validate --config /etc/caddy/Caddyfile
+
+# 格式化配置
+sudo caddy fmt --overwrite /etc/caddy/Caddyfile
+
+# 查看证书
+sudo caddy cert-info  # 或直接访问 https://域名 看浏览器锁
+```
+
+## 添加新服务
+
+在 `/etc/caddy/Caddyfile` 里加一行 block：
+
+```
+你的子域名.xybkwd.top {
+    reverse_proxy localhost:服务端口
+}
+```
+
+然后 `sudo caddy fmt --overwrite /etc/caddy/Caddyfile && sudo systemctl restart caddy`
+
+Let's Encrypt 会在第一次 HTTPS 请求时自动签发证书，续期也是全自动的。
+
+## 故障排查
+
+| 现象 | 排查 |
+|:---|:---|
+| 域名无法访问 | `curl -sk https://localhost:443 -H "Host: 域名"` |
+| 证书错误 | `echo \| openssl s_client -connect localhost:443 -servername 域名` |
+| Caddy 启动失败 | `sudo journalctl -u caddy --no-pager -n 30` |
+| 端口被占 | `sudo ss -tlnp \| grep ":80\|:443"` |
+
+## 安全说明
+
+- Caddy 管理 API 只在 `localhost:2019`，外网不可达
+- 所有证书使用 Let's Encrypt，自动续期（3个月）
+- 后端服务（Gitea:3000, Dashboard:9000）已绑定 `127.0.0.1`，只能通过 Caddy 访问