# Truy cập SSH qua proxy

Tác nhân cần chạy lệnh trên máy từ xa — triển khai container, đọc log, sửa cấu hình. Giao khóa riêng SSH thô cho LLM là ý tồi: khóa lọt vào cửa sổ ngữ cảnh, log và bản ghi. Proxy SSH giải quyết điều này: nó giữ thông tin xác thực, tác nhân chỉ nói HTTP.

## Mô hình

```
LLM ──HTTPS──► Proxy SSH ──SSH──► máy đích
                (giữ khóa,
                 nhật ký kiểm toán,
                 giới hạn tần suất)
```

Proxy cung cấp phiên bền vững qua mặt REST đơn giản:

| Endpoint | Mục đích |
|---|---|
| `POST /connect?target=vps1` | mở phiên → `session_id` |
| `POST /<sid>/exec` `{command, timeout}` | chạy lệnh (async) → `exec_id` |
| `GET /<sid>/exec/<exec_id>` | thăm dò đầu ra |
| Endpoint SFTP | tải lên/xuống tệp, `ls`, `mkdir`, `rm` |

Xác thực là token Bearer — cùng mẫu với mọi API khác bạn dùng.

## Mẫu thực thi

```bash
# 1. kết nối một lần, tái sử dụng phiên cho cả tác vụ
SID=$(curl -s -H "Authorization: Bearer $KEY" \
  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)

# 2. chạy một lệnh
EID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -X POST "https://ssh-proxy.example/$SID/exec" \
  -d '{"command": "docker ps --format \"{{.Names}}\"", "timeout": 120}' | jq -r .exec_id)

# 3. thăm dò kết quả
curl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"
```

## Quy tắc thao tác

1. **Tái sử dụng phiên.** Kết nối cho từng lệnh lãng phí tài nguyên và đụng giới hạn tần suất. Lưu `session_id` (vd. `/tmp/vps1_sid`) và gửi heartbeat trước khi tái dùng.
2. **Đặt tên mục tiêu, đừng dò tìm.** Mục tiêu được đăng ký trước (`vps1`, `pi`, …). Proxy là nguồn chân lý duy nhất — không bao giờ mã hóa cứng địa chỉ IP vào mã tác nhân.
3. **Ưu tiên SFTP hơn cat/heredoc của shell cho tệp.** Escape dữ liệu nhị phân qua `exec` làm hỏng tải trọng. Dùng endpoint tải lên/xuống chuyên dụng.
4. **Bọc lệnh của bạn trong dấu ngoặc.** Thân JSON được phân tích hai lần (HTTP + shell). Bọc lệnh từ xa trong ngoặc đơn và giữ một dòng.
5. **Giả định có kiểm toán.** Mỗi lệnh exec vào nhật ký kiểm toán của proxy — hành xử như con người đọc mọi thứ (họ có thể).

## Khi nào KHÔNG dùng exec

- Đọc trạng thái có cấu trúc đã có API (Docker, cơ sở dữ liệu, Mind API của Synapse) — luôn ưu tiên API hơn phân tích đầu ra CLI.
- Tiến trình tương tác dài hạn. `exec` là fire-and-forget có thời hạn; thay vào đó dùng `nohup` + tệp trạng thái trên máy đích.
- Bất kỳ điều gì phá hoại mà không có chỉ thị rõ ràng. Proxy cho bạn quyền lực — con người cho bạn sự cho phép.

## Khôi phục lỗi

| Triệu chứng | Cách xử lý |
|---|---|
| 401 khi connect | token hết hạn — đọc lại từ memory/settings, không bao giờ từ bản ghi |
| phiên 404 | phiên hết hạn (trần 24h) — kết nối lại |
| exec quá hạn | tăng `timeout` hoặc chia nhỏ lệnh; kiểm tra tải máy đích |
| nội dung tệp hỏng | bạn dùng `exec` thay vì SFTP — chuyển sang endpoint SFTP |