momentry_core_0_1/docs/INSTALL_CADDY.md

Caddy 安裝指南 (本地部署)

概述

本文檔說明如何在 macOS 上安裝 Caddy Web Server，配置為本地部署，作為反向代理伺服器。

---

當前狀態

項目	狀態
Caddy	✅ 已安裝 v2.10.2
設定檔	/Users/accusys/momentry/etc/Caddyfile
日誌目錄	/Users/accusys/momentry/log/
Plist	/Library/LaunchDaemons/com.momentry.caddy.plist

---

安裝步驟

Step 1: 安裝 Caddy (使用 brew)

# 安裝 Caddy
brew install caddy

驗證:

caddy --version
# v2.10.2

---

Step 2: 建立目錄

# 建立配置目錄
mkdir -p /Users/accusys/momentry/etc/caddy

# 建立日誌目錄
mkdir -p /Users/accusys/momentry/log

# 建立數據目錄
mkdir -p /Users/accusys/momentry/var/caddy

# 建立日誌文件
touch /Users/accusys/momentry/log/caddy.log
touch /Users/accusys/momentry/log/caddy.error.log

# 設定權限
# 注意: Caddy 使用 ports 80/443，必須以 root 身份運行
# 因此 var/caddy 目錄需要 root:admin 權限
chown -R accusys:staff /Users/accusys/momentry/etc/caddy
chown -R accusys:staff /Users/accusys/momentry/log
sudo chown -R root:admin /Users/accusys/momentry/var/caddy

---

Step 3: 建立設定檔

建立 /Users/accusys/momentry/etc/Caddyfile:

{
	email admin@accusys.com.tw
	metrics
}

# 定義日誌 Snippet
(common_log) {
	log {
		output file /Users/accusys/momentry/log/{args[0]}.log {
			roll_size 100mb
			roll_keep 5
			roll_keep_for 720h
		}
		format json
	}
}

# Example: 反向代理到本地服務
example.momentry.ddns.net {
	reverse_proxy localhost:8080 {
		header_up Host {upstream_hostport}
	}
	import common_log example_access
}

---

Step 4: 使用 plist 開機自動啟動

注意: Caddy 需要使用 ports 80 和 443，必須以 root 身份運行。

# 複製 plist 到 LaunchDaemons 目錄
sudo cp /Users/accusys/momentry_core_0.1/momentry_runtime/plist/com.momentry.caddy.plist /Library/LaunchDaemons/

# 載入並啟動
sudo launchctl load /Library/LaunchDaemons/com.momentry.caddy.plist

---

監控配置

添加到監控配置

在 monitor/config/monitor_config.yaml 中添加：

service:
  services:
    - name: "caddy"
      type: "http"
      port: 80
      host: "localhost"
      check_url: "http://localhost:2019/config/"
      timeout: 5
      enabled: true

---

卸載步驟

重要: 路徑說明

路徑	類型	說明
/Users/accusys/momentry/etc/caddy/	配置	不要刪除 - Caddy 配置
/Users/accusys/momentry/log/	日誌	不要刪除 - 日誌目錄
/Users/accusys/momentry/var/caddy/	數據	不要刪除 - Caddy 數據
/opt/homebrew/opt/caddy/	安裝	刪除 - Caddy 安裝目錄
/opt/homebrew/opt/caddy/	安裝	刪除 - Caddy 安裝目錄

Step 1: 停止 Caddy

# 找到 Caddy 進程
ps aux | grep caddy | grep -v grep

# 停止 Caddy
pkill caddy

# 確認停止
ps aux | grep caddy | grep -v grep || echo "Caddy 已停止"

---

Step 2: 卸載 Caddy

# 卸載 Caddy
brew uninstall caddy

# 移除 plist
sudo launchctl unload /Library/LaunchDaemons/com.momentry.caddy.plist
sudo rm /Library/LaunchDaemons/com.momentry.caddy.plist

---

Step 3: 刪除專屬檔案

# 刪除配置目錄 (可選)
rm -rf /Users/accusys/momentry/etc/Caddyfile

# 刪除日誌 (可選)
rm -f /Users/accusys/momentry/log/caddy.log
rm -f /Users/accusys/momentry/log/caddy.error.log

# 刪除數據目錄 (可選)
rm -rf /Users/accusys/momentry/var/caddy

注意: 不要刪除以下共用目錄:

# 這些是共用的，不要刪除!
# /Users/accusys/momentry/etc
# /Users/accusys/momentry/log
# /Users/accusys/momentry/var

---

Step 4: 卸載後檢查清單

echo "=== Caddy 卸載後檢查 ==="

# 1. 檢查 Caddy 進程
echo "1. Caddy 進程:"
ps aux | grep caddy | grep -v grep && echo "   ✗ 仍在運行" || echo "   ✓ 已停止"

# 2. Port 80/443
echo "2. Port 80/443:"
(lsof -i :80 > /dev/null 2>&1 || lsof -i :443 > /dev/null 2>&1) && echo "   ✗ 仍被佔用" || echo "   ✓ 已釋放"

# 3. caddy 命令
echo "3. caddy 命令:"
which caddy > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 4. brew 安裝
echo "4. brew 安裝:"
brew list caddy > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 5. launchctl 服務
echo "5. launchctl 服務:"
sudo launchctl list | grep caddy > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 6. 配置目錄 (可選刪除)
echo "6. 配置目錄:"
[ -d "/Users/accusys/momentry/etc" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"

# 7. 日誌目錄 (可選刪除)
echo "7. 日誌目錄:"
[ -d "/Users/accusys/momentry/log" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"

預期結果:

=== Caddy 卸載後檢查 ===
1. Caddy 進程:
   ✓ 已停止
2. Port 80/443:
   ✓ 已釋放
3. caddy 命令:
   ✓ 已移除
4. brew 安裝:
   ✓ 已移除
5. launchctl 服務:
   ✓ 已移除
6. 配置目錄:
   ✓ 保留 (或 ✗ 已刪除)
7. 日誌目錄:
   ✓ 保留 (或 ✗ 已刪除)

---

手動檢查命令

# 1. 檢查進程
ps aux | grep caddy | grep -v grep

# 2. 檢查 Port
lsof -i :80
lsof -i :443
lsof -i :2019

# 3. 測試配置語法
caddy validate --config /Users/accusys/momentry/etc/Caddyfile

# 4. 查看 Caddy 版本
caddy version

# 5. 重新載入配置
caddy reload --config /Users/accusys/momentry/etc/Caddyfile

# 6. 查看日誌
tail -20 /Users/accusys/momentry/log/caddy.log

# 7. 查看 Caddy 適配的網站
curl -I http://localhost:2019/config/

---

Caddyfile 範例

基本反向代理

{
	email admin@accusys.com.tw
}

# 反向代理到本地服務
example.local {
	reverse_proxy localhost:8080
}

帶 SSL 的反向代理

{
	email admin@accusys.com.tw
}

# 使用 Let's Encrypt 自動 SSL
example.momentry.ddns.net {
	reverse_proxy localhost:8080 {
		header_up Host {upstream_hostport}
	}
}

多站點配置

{
	email admin@accusys.com.tw
}

# 站點 1
site1.example.com {
	reverse_proxy localhost:8080
}

# 站點 2
site2.example.com {
	reverse_proxy localhost:8081
}

---

環境變數

在 .env 中:

CADDY_CONFIG=/Users/accusys/momentry/etc/Caddyfile
CADDY_HOME=/Users/accusys/.local/share/caddy

---

故障排除

Caddy 無法啟動

# 檢查日誌
tail -f /Users/accusys/momentry/log/caddy.log

# 檢查配置語法
caddy validate --config /Users/accusys/momentry/etc/Caddyfile

# 檢查目錄權限
ls -la /Users/accusys/momentry/etc/

# 重新設定權限
chown -R $(whoami):staff /Users/accusys/momentry/etc

Port 被佔用

# 檢查哪個程序佔用 port 80
lsof -i :80

# 終止佔用程序
kill <PID>

需要重新載入配置

# 重新載入配置 (熱重載)
caddy reload --config /Users/accusys/momentry/etc/Caddyfile

# 或者停止後重新啟動
sudo launchctl unload /Library/LaunchDaemons/com.momentry.caddy.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.caddy.plist

---

檔案位置

類型	路徑	說明
安裝	/opt/homebrew/opt/caddy/	Caddy 安裝目錄
執行檔	/opt/homebrew/opt/caddy/bin/caddy	Caddy 執行檔
配置	/Users/accusys/momentry/etc/Caddyfile	設定檔
日誌	/Users/accusys/momentry/log/caddy.log	執行日誌
錯誤日誌	/Users/accusys/momentry/log/caddy.error.log	錯誤日誌
數據	/Users/accusys/momentry/var/caddy/	Caddy 數據目錄
plist	/Library/LaunchDaemons/com.momentry.caddy.plist	開機啟動
備份	/Users/accusys/momentry/var/caddy_backup/Caddyfile	配置備份

---

常用指令

# 驗證配置
caddy validate --config /Users/accusys/momentry/etc/Caddyfile

# 熱重載配置
caddy reload --config /Users/accusys/momentry/etc/Caddyfile

# 停止 Caddy
caddy stop

# 啟動 Caddy
caddy start --config /Users/accusys/momentry/etc/Caddyfile

# 適配所有網站
caddy adapt --config /Users/accusys/momentry/etc/Caddyfile --adapter caddyfile

---

備份與恢復

備份

TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/Users/accusys/momentry/backup/daily/caddy"

mkdir -p "$BACKUP_DIR"

# 備份配置
tar -czf "$BACKUP_DIR/caddy_cfg_${TIMESTAMP}.tar.gz" \
    /Users/accusys/momentry/etc/Caddyfile

# 驗證
sha256sum "$BACKUP_DIR/caddy_cfg_${TIMESTAMP}.tar.gz" > "$BACKUP_DIR/caddy_${TIMESTAMP}.sha256"

恢復

# 解壓配置
tar -xzf /Users/accusys/momentry/backup/daily/caddy/caddy_cfg_20260316_102416.tar.gz -C /

# 驗證並重載
caddy validate --config /Users/accusys/momentry/etc/Caddyfile
caddy reload --config /Users/accusys/momentry/etc/Caddyfile

---

版本資訊

• 版本: 2.10.2
• 配置: /Users/accusys/momentry/etc/Caddyfile
• 日誌目錄: /Users/accusys/momentry/log/