# 运维连接手册（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`，不要只在 `~/` 下面找。