docs: add CLAUDE.md with patch history and ops runbook

2026-06-24 18:56:35 +09:00
parent 1924a56b13
commit fd26f8de88
1 changed files with 106 additions and 0 deletions
@@ -0,0 +1,106 @@
+# xboard-node fork 运维手册
+
+## 仓库说明
+
+JP01 Gitea 自维护 fork，**不是上游镜像**，独立分支。
+
+- 本仓库：`http://103.112.1.141:3000/will/xboard-node`（dev 分支）
+- 上游（仅供 cherry-pick 参考）：`https://github.com/cedar2025/Xboard-Node`
+- 工作目录：`/tmp/xboard-node`（JP01）
+
+---
+
+## 已应用补丁
+
+| 补丁 | 文件 | 说明 | 是否可移除 |
+|------|------|------|-----------|
+| #32 | `internal/service/service.go` | ban 用户前调 `CloseUserConnections()`，立即断连 | 待上游合并后移除 |
+| #55 | `internal/kernel/singbox/conntracker.go` | UDP PacketConn upload/download 计数对调 | 待上游合并后移除 |
+| 自改 | `cmd/xbctl/main.go` | `downloadBase` 指向 JP01 Gitea releases | 永久保留 |
+| 自改 | `cmd/xbctl/main.go` | `downloadToken` + `downloadFile` 加 Authorization header，支持 private 仓库下载 | 永久保留 |
+| 自改 | `install.sh` | binary 下载地址改为 JP01 Gitea releases | 永久保留 |
+
+### xbctl private 仓库下载（2026-06-24）
+
+**背景**：Gitea 仓库改为 private 后，`xbctl upgrade` 下载时 HTTP 401。
+
+**改动位置**：`cmd/xbctl/main.go`
+
+```go
+// 新增常量
+downloadToken = "cf6634b57d2c60c66030dbb29d77c4ed25370e94"
+
+// downloadFile 改用 NewRequest，加 Authorization header
+func downloadFile(url, dest string) error {
+    client := &http.Client{Timeout: 120 * time.Second}
+    req, err := http.NewRequest("GET", url, nil)
+    if err != nil {
+        return err
+    }
+    if downloadToken != "" {
+        req.Header.Set("Authorization", "token "+downloadToken)
+    }
+    resp, err := client.Do(req)
+    ...
+}
+```
+
+**注意**：token 是只读 `read:repository` 权限，泄露只能读仓库，不能写。
+
+---
+
+## 编译命令
+
+```bash
+cd /tmp/xboard-node
+VERSION=$(git describe --tags --always --dirty)
+
+# xboard-node（必须带这些 tags）
+CGO_ENABLED=0 /usr/local/go/bin/go build \
+  -ldflags "-s -w -X main.version=${VERSION}" \
+  -tags "with_quic with_utls with_wireguard with_acme with_clash_api" \
+  -o xboard-node-linux-amd64 ./cmd/xboard-node/
+
+# xbctl
+CGO_ENABLED=0 /usr/local/go/bin/go build \
+  -ldflags "-s -w" \
+  -o xbctl-linux-amd64 ./cmd/xbctl/
+```
+
+---
+
+## 发布流程
+
+```bash
+TOKEN=cf6634b57d2c60c66030dbb29d77c4ed25370e94
+RELEASE_ID=14  # v1.13-patched
+
+# 删旧 asset
+OLD_ID=$(curl -s "http://localhost:3000/api/v1/repos/will/xboard-node/releases/$RELEASE_ID/assets" \
+  -H "Authorization: token $TOKEN" | python3 -c "
+import sys,json
+for a in json.load(sys.stdin):
+    if a['name'] == 'xboard-node-linux-amd64': print(a['id'])")
+curl -s -X DELETE "http://localhost:3000/api/v1/repos/will/xboard-node/releases/$RELEASE_ID/assets/$OLD_ID" \
+  -H "Authorization: token $TOKEN"
+
+# 上传新 asset
+curl -s -X POST "http://localhost:3000/api/v1/repos/will/xboard-node/releases/$RELEASE_ID/assets?name=xboard-node-linux-amd64" \
+  -H "Authorization: token $TOKEN" -H "Content-Type: application/octet-stream" \
+  --data-binary @xboard-node-linux-amd64
+```
+
+---
+
+## 节点部署
+
+| 节点 | IP | MCP |
+|------|----|-----|
+| dmit-tyo | 154.31.113.157 | mcp__dmit-tyo__exec |
+| us-unlock | 103.152.113.30 | mcp__us-unlock__exec |
+| vmiss-us01 | 38.47.112.162 | mcp__vmiss-us04__exec |
+
+节点上执行升级：
+```bash
+xbctl upgrade  # 自动带 token，直接用
+```