# 服务器排查与配置完整记录

> 适用场景：阿里云 ECS + Ubuntu/Debian + Caddy + Cloudflare DNS + pnpm 项目部署
> 时间：2026-07-15
> 服务器 IP：8.140.26.94

---

## 一、问题总览

| 序号 | 问题 | 现象 | 根因 | 状态 |
|---|---|---|---|---|
| 1 | Caddy 编译失败 | `checksum mismatch` 安全错误 | 阿里云 Go 代理 `mirrors.aliyun.com/goproxy` 与官方 `sum.golang.org` 校验和不一致 | ✅ 已解决 |
| 2 | xcaddy 命令报错 | `go.mod file not found` | 在非 Go 项目目录执行 `xcaddy list-modules` | ✅ 已解决 |
| 3 | Caddy 插件未生效 | `/usr/bin/caddy` 仍是旧版本 | 未替换系统 Caddy 二进制 | ✅ 已解决 |
| 4 | Caddyfile 配置错误 | 证书申请异常 | `tls` 块重复写了两次 | ✅ 已修复 |
| 5 | HTTPS 浏览器不通 | `https://test.xintechai.com` 无法访问 | 阿里云安全组未放行 443 端口 | ✅ 已解决 |
| 6 | pnpm install 卡住 | 超时无输出 | Electron 二进制需从 GitHub 下载，国内直连极慢 | ✅ 已解决 |

---

## 二、Caddy + Cloudflare DNS 插件编译与部署

### 2.1 问题现象

```bash
xcaddy build --with github.com/caddy-dns/cloudflare
```

报错：
```
verifying module: checksum mismatch
    downloaded: h1:VLwUxc9dg9O3qRXKYvwSvFPc/92ZVLXlTnDoYbFj9bk=
    sum.golang.org: h1:Wq6gYXlsY6ubqI3hhxsTzdyotvfdjFBxuwYqCLCnj/U=
SECURITY ERROR
```

### 2.2 根因分析

- `GOPROXY` 设置为 `https://mirrors.aliyun.com/goproxy/`
- `GOSUMDB` 仍为官方 `sum.golang.org`
- 镜像缓存的模块 zip 包与官方校验和数据库记录不一致，Go 安全机制拦截

### 2.3 解决方案

切换为国内兼容性更好的代理，并清理冲突缓存：

```bash
# 1. 修改 Go 代理配置
go env -w GOPROXY="https://goproxy.cn,https://proxy.golang.org,direct"
go env -w GOSUMDB="sum.golang.org"
go env -w GONOSUMDB=""

# 2. 清理模块缓存
go clean -modcache
rm -rf /root/go/pkg/mod/cache/download

# 3. 重新编译
xcaddy build --with github.com/caddy-dns/cloudflare --output /root/caddy
```

### 2.4 替换系统 Caddy

```bash
# 备份旧版本
cp /usr/bin/caddy /usr/bin/caddy.bak

# 停止服务
systemctl stop caddy

# 替换二进制
cp /root/caddy /usr/bin/caddy
chmod +x /usr/bin/caddy

# 赋予绑定特权端口权限（如需要）
setcap cap_net_bind_service=+ep /usr/bin/caddy

# 重启服务
systemctl restart caddy
```

### 2.5 验证插件

```bash
/usr/bin/caddy list-modules | grep cloudflare
# 预期输出：dns.providers.cloudflare
```

---

## 三、Caddyfile 配置与证书申请

### 3.1 原始问题配置（错误）

```caddy
test.xintechai.com {
    tls {
        dns cloudflare 4QcTRfKJAaAnzVhWwYSiPB74SMsSdt20OW1N5_qr
    }
    tls {
        dns cloudflare 4QcTRfKJAaAnzVhWwYSiPB74SMsSdt20OW1N5_qr
    }
    ...
}
```

**错误**：`tls` 块重复了两次，Caddy 解析失败。

### 3.2 修复后配置

```caddy
# 全局选项
{
    # 可选：全局配置 Cloudflare DNS
    # acme_dns cloudflare {env.CF_API_TOKEN}
}

:80 {
    root * /usr/share/caddy
    file_server
}

test.xintechai.com {
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }

    reverse_proxy 127.0.0.1:8080

    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Frame-Options "DENY"
        X-Content-Type-Options "nosniff"
        -Server
    }
}
```

### 3.3 环境变量持久化（systemd）

创建环境变量文件：

```bash
cat > /etc/caddy/caddy.env << 'EOF'
CF_API_TOKEN=你的Cloudflare_Token
EOF
```

创建 systemd override：

```bash
mkdir -p /etc/systemd/system/caddy.service.d
cat > /etc/systemd/system/caddy.service.d/override.conf << 'EOF'
[Service]
EnvironmentFile=/etc/caddy/caddy.env
EOF

systemctl daemon-reload
systemctl restart caddy
```

### 3.4 验证证书申请

```bash
# 查看证书获取日志
journalctl -u caddy -f
```

成功标志：
```
logger=http.acme_client msg="validations succeeded; finalizing order"
logger=tls.obtain msg="certificate obtained successfully"
```

---

## 四、HTTPS 不通排查（阿里云安全组）

### 4.1 排查过程

| 步骤 | 命令 | 结果 | 结论 |
|---|---|---|---|
| 1 | `curl -sk https://localhost/` | 本地 SNI 握手失败 | 证书可能有问题 |
| 2 | `openssl s_client -connect localhost:443` | 证书正常（Let's Encrypt） | 证书本身 OK |
| 3 | `curl --resolve test.xintechai.com:443:127.0.0.1 https://test.xintechai.com` | **HTTP 200** | Caddy 本地完全正常 |
| 4 | `curl -sk https://test.xintechai.com`（不指定 IP）| **超时/失败** | 外部网络到 443 被拦截 |

### 4.2 根因

**阿里云安全组默认不放行 443 端口**，只放行 22（SSH）和 80（HTTP）。

### 4.3 解决方案

阿里云控制台 → ECS → 安全组 → 配置规则 → 入方向 → 添加：

| 类型 | 端口范围 | 授权对象 | 描述 |
|---|---|---|---|
| 自定义 TCP | `443/443` | `0.0.0.0/0` | HTTPS |
| 自定义 TCP | `443/443` | `::/0` | HTTPS IPv6 |

**支持端口范围写法**：
- `80/443` — 同时放行 HTTP + HTTPS
- `3000/3010` — 放行 3000~3010 共 11 个端口

保存后**即时生效**，无需重启服务器。

### 4.4 验证

```bash
curl -I https://test.xintechai.com
# HTTP/2 200
```

---

## 五、pnpm install 超时问题（Electron 项目）

### 5.1 问题现象

```bash
cd /root/workspace/aliyunworkspace/forge
pnpm install
# 卡住 2 分钟+ 无输出，最终超时
```

### 5.2 根因分析

- `electron@40.8.0` 的 `postinstall` 脚本需从 **GitHub Releases** 下载 ~150MB 二进制
- 国内直连 GitHub 极慢/超时
- `.npmrc` 缺少 `electron_mirror` 配置

### 5.3 解决方案

**步骤 1：清理旧环境**

```bash
rm -rf node_modules pnpm-lock.yaml
```

**步骤 2：配置 `.npmrc`**

```ini
shamefully-hoist=true
registry=https://registry.npmmirror.com
electron_mirror=https://npmmirror.com/mirrors/electron/
electron_builder_binaries_mirror=https://npmmirror.com/mirrors/electron-builder-binaries/
```

**步骤 3：重新安装**

```bash
pnpm install
```

结果：`Done in 1m 34.1s`

### 5.4 关键镜像地址汇总

| 用途 | 镜像地址 |
|---|---|
| npm 包 | `https://registry.npmmirror.com` |
| Electron 二进制 | `https://npmmirror.com/mirrors/electron/` |
| Electron Builder 二进制 | `https://npmmirror.com/mirrors/electron-builder-binaries/` |
| Go 模块代理 | `https://goproxy.cn` |

---

## 六、常用验证命令速查

### Caddy

```bash
# 查看版本和插件
caddy version
caddy list-modules | grep cloudflare

# 验证配置
caddy validate --config /etc/caddy/Caddyfile

# 查看证书
openssl s_client -connect test.xintechai.com:443 -servername test.xintechai.com </dev/null | openssl x509 -noout -dates -subject

# 实时日志
journalctl -u caddy -f
```

### 网络

```bash
# 查看监听端口
ss -tlnp | grep -E "80|443"

# 本地绕过 DNS 测试
curl -skv --resolve test.xintechai.com:443:127.0.0.1 https://test.xintechai.com/

# 公网测试
curl -I https://test.xintechai.com
```

### pnpm / Node

```bash
# 查看当前镜像源
pnpm config get registry
npm config get registry

# 强制使用官方源（应急）
pnpm install --registry=https://registry.npmjs.org

# 仅查看安装进度
pnpm install --reporter=append-only
```

---

## 七、安全配置建议

### ⚠️ API Token 泄露风险

- **Cloudflare API Token** 曾暴露在 `Caddyfile` 明文和聊天记录中
- 已迁移到独立环境文件 `/etc/caddy/caddy.env`
- **建议**：去 Cloudflare 控制台重新生成 Token，替换后重启 Caddy

```bash
systemctl restart caddy
```

### 防火墙最小化原则

- 安全组只放行必要端口（80/443/22）
- 业务端口建议绑定 `127.0.0.1`，通过 Caddy 反向代理暴露

---

## 八、最终状态确认

| 服务 | 状态 | 监听 |
|---|---|---|
| Caddy | `active (running)` | `:80`, `:443` |
| Cloudflare DNS 插件 | ✅ 已加载 | `dns.providers.cloudflare` |
| Let's Encrypt 证书 | ✅ 有效 | 2026-07-15 ~ 2026-10-13 |
| HTTPS 公网访问 | ✅ 畅通 | `https://test.xintechai.com` |
| forge 项目依赖 | ✅ 安装完成 | `pnpm install` 1m34s |

---

> 文档生成时间：2026-07-15
> 可直接复制粘贴到钉钉文档、语雀、Notion 等支持 Markdown 的平台