From b3bc2d825021216e611f3c24560c8a6b98a0db75 Mon Sep 17 00:00:00 2001
From: fanziqi <403508380@qq.com>
Date: Tue, 31 Mar 2026 14:15:22 +0800
Subject: [PATCH] docs: add cloud sql and server connection runbook

---
 README.md               |   6 +-
 docs/OPS_CONNECTIONS.md | 147 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 152 insertions(+), 1 deletion(-)
 create mode 100644 docs/OPS_CONNECTIONS.md

diff --git a/README.md b/README.md
index fc7ade7..bbe27f6 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,7 @@
 # arbitrage-engine
 
-资金费率套利引擎 BTC/ETH 现货+永续对冲
\ No newline at end of file
+资金费率套利引擎 BTC/ETH 现货+永续对冲
+
+## Docs
+
+- 运维连接手册（Cloud SQL + GCE）: [docs/OPS_CONNECTIONS.md](docs/OPS_CONNECTIONS.md)
diff --git a/docs/OPS_CONNECTIONS.md b/docs/OPS_CONNECTIONS.md
new file mode 100644
index 0000000..edf5f7a
--- /dev/null
+++ b/docs/OPS_CONNECTIONS.md
@@ -0,0 +1,147 @@
+# 运维连接手册（Cloud SQL + GCE）
+
+本手册记录本项目当前线上环境的关键连接信息。
+目标：后续只看这一个文档，就能快速连上数据库和服务器。
+
+## 0. 固定信息
+
+- GCP Project ID: `gen-lang-client-0835616737`
+- Cloud SQL instance connection name: `gen-lang-client-0835616737:asia-northeast1:arb-db`
+- Cloud SQL DB: `arb_engine`
+- DB user: `arb`
+- DB password (当前): `arb_engine_2026`
+- 线上 VM: `instance-20260221-064508`
+- Zone: `asia-northeast1-b`
+- 线上项目目录: `/home/fzq1228/Projects/arbitrage-engine`
+
+## 1. 本机连接 Cloud SQL
+
+### 1.1 启动 Proxy（本机）
+
+开一个终端窗口常驻运行：
+
+```bash
+cloud-sql-proxy gen-lang-client-0835616737:asia-northeast1:arb-db --port 9470
+```
+
+如果系统找不到命令，用完整路径：
+
+```bash
+/opt/homebrew/share/google-cloud-sdk/bin/cloud-sql-proxy \
+  gen-lang-client-0835616737:asia-northeast1:arb-db \
+  --port 9470
+```
+
+### 1.2 测试 DB 连通性
+
+```bash
+PGPASSWORD=arb_engine_2026 psql -h 127.0.0.1 -p 9470 -U arb -d arb_engine -c "SELECT 1;"
+```
+
+进入交互式 SQL：
+
+```bash
+PGPASSWORD=arb_engine_2026 psql -h 127.0.0.1 -p 9470 -U arb -d arb_engine
+```
+
+### 1.3 Proxy 常见修复
+
+如果报错类似 `server closed the connection unexpectedly` 或 `connection refused`：
+
+```bash
+pkill -f "cloud-sql-proxy gen-lang-client-0835616737:asia-northeast1:arb-db --port 9470" || true
+cloud-sql-proxy gen-lang-client-0835616737:asia-northeast1:arb-db --port 9470
+```
+
+## 2. 连接线上服务器（GCE）
+
+### 2.1 先确认账号和项目
+
+```bash
+gcloud auth list --filter=status:ACTIVE --format='value(account)'
+gcloud config get-value project
+```
+
+如需切换项目：
+
+```bash
+gcloud config set project gen-lang-client-0835616737
+```
+
+### 2.2 查看实例
+
+```bash
+gcloud compute instances list --format='table(name,zone,status,networkInterfaces[0].networkIP,networkInterfaces[0].accessConfigs[0].natIP)'
+```
+
+### 2.3 SSH（推荐 IAP）
+
+注意：该实例直连 22 端口可能失败，推荐固定用 IAP：
+
+```bash
+gcloud compute ssh instance-20260221-064508 \
+  --zone asia-northeast1-b \
+  --project gen-lang-client-0835616737 \
+  --tunnel-through-iap
+```
+
+快速连通性测试：
+
+```bash
+gcloud compute ssh instance-20260221-064508 \
+  --zone asia-northeast1-b \
+  --project gen-lang-client-0835616737 \
+  --tunnel-through-iap \
+  --command "hostname; whoami; uptime; pwd"
+```
+
+## 3. 线上项目目录与运行状态
+
+### 3.1 项目目录
+
+- Repo root: `/home/fzq1228/Projects/arbitrage-engine`
+- Backend: `/home/fzq1228/Projects/arbitrage-engine/backend`
+- Frontend: `/home/fzq1228/Projects/arbitrage-engine/frontend`
+
+### 3.2 当前运行形态（关键）
+
+- 运行用户：`fzq1228`
+- 进程管理：`pm2`（PM2 God Daemon 在跑）
+- 关键进程：
+  - `python3 signal_engine.py`
+  - `python3 paper_monitor.py`
+  - `uvicorn main:app --host 0.0.0.0 --port 4332`
+  - `next start -p 4333`
+
+进程核对命令：
+
+```bash
+ps -ef | egrep -i 'signal_engine|paper_monitor|uvicorn|next start|PM2' | grep -v egrep
+```
+
+## 4. 常用线上操作命令
+
+进入项目目录：
+
+```bash
+cd /home/fzq1228/Projects/arbitrage-engine
+```
+
+查看分支和最近提交（避免 safe.directory 报错）：
+
+```bash
+sudo git -c safe.directory=/home/fzq1228/Projects/arbitrage-engine -C /home/fzq1228/Projects/arbitrage-engine rev-parse --abbrev-ref HEAD
+sudo git -c safe.directory=/home/fzq1228/Projects/arbitrage-engine -C /home/fzq1228/Projects/arbitrage-engine log --oneline -1
+```
+
+## 5. 快速故障排查
+
+- DB 报 `connection refused`
+  - Proxy 没开或者端口不是 `9470`。
+- DB 报 `server closed the connection unexpectedly`
+  - 通常是旧 Proxy 假活着，重启 Proxy。
+- SSH 报 `Connection closed by ... port 22`
+  - 改用 `--tunnel-through-iap`。
+- 能 SSH 但找不到项目目录
+  - 当前在线项目目录固定是 `/home/fzq1228/Projects/arbitrage-engine`，不要只在 `~/` 下面找。
+