{"title":"Truy cập SSH qua proxy","slug":"ssh-proxy-access","category":"llm-cookbook","summary":"Tác nhân LLM chạy lệnh trên máy từ xa an toàn qua API proxy SSH thay vì khóa SSH thô như thế nào.","audience":["llm"],"tags":["cookbook","ssh","proxy","infrastructure","remote-execution"],"difficulty":"intermediate","updated":"2026-09-26","word_count":451,"read_minutes":2,"llm_context":"KHÔNG BAO GIỜ giữ khóa riêng SSH thô với tư cách LLM. Dùng HTTP API proxy SSH:\n1) POST /connect?target= → session_id (bền vững, sống qua hàng giờ).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → đầu ra khi xong.\n4) Dùng endpoint SFTP cho tải lên/xuống tệp thay vì cat/heredoc.\nMục tiêu là tên đăng ký trước (vd. \"vps1\"), không phải IP — proxy là nơi duy\nnhất chứa thông tin xác thực.\n","lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Truy cập SSH qua proxy\n\nTá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.\n\n## Mô hình\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► máy đích\n (giữ khóa,\n nhật ký kiểm toán,\n giới hạn tần suất)\n```\n\nProxy cung cấp phiên bền vững qua mặt REST đơn giản:\n\n| Endpoint | Mục đích |\n|---|---|\n| `POST /connect?target=vps1` | mở phiên → `session_id` |\n| `POST //exec` `{command, timeout}` | chạy lệnh (async) → `exec_id` |\n| `GET //exec/` | thăm dò đầu ra |\n| Endpoint SFTP | tải lên/xuống tệp, `ls`, `mkdir`, `rm` |\n\nXác thực là token Bearer — cùng mẫu với mọi API khác bạn dùng.\n\n## Mẫu thực thi\n\n```bash\n# 1. kết nối một lần, tái sử dụng phiên cho cả tác vụ\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. chạy một lệnh\nEID=$(curl -s -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -X POST \"https://ssh-proxy.example/$SID/exec\" \\\n -d '{\"command\": \"docker ps --format \\\"{{.Names}}\\\"\", \"timeout\": 120}' | jq -r .exec_id)\n\n# 3. thăm dò kết quả\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Quy tắc thao tác\n\n1. **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.\n2. **Đặ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.\n3. **Ư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.\n4. **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.\n5. **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ể).\n\n## Khi nào KHÔNG dùng exec\n\n- Đọ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.\n- 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.\n- 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.\n\n## Khôi phục lỗi\n\n| Triệu chứng | Cách xử lý |\n|---|---|\n| 401 khi connect | token hết hạn — đọc lại từ memory/settings, không bao giờ từ bản ghi |\n| phiên 404 | phiên hết hạn (trần 24h) — kết nối lại |\n| exec quá hạn | tăng `timeout` hoặc chia nhỏ lệnh; kiểm tra tải máy đích |\n| nội dung tệp hỏng | bạn dùng `exec` thay vì SFTP — chuyển sang endpoint SFTP |\n","content_html":"

Truy cập SSH qua proxy

\n

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.

\n

Mô hình

\n
LLM ──HTTPS──► Proxy SSH ──SSH──► máy đích\n                (giữ khóa,\n                 nhật ký kiểm toán,\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:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointMục đích
POST /connect?target=vps1mở 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 SFTPtải lên/xuống tệp, ls, mkdir, rm
\n

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

\n

Mẫu thực thi

\n
# 1. kết nối một lần, tái sử dụng phiên cho cả tác vụ\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. chạy một lệnh\nEID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \\\n  -X POST "https://ssh-proxy.example/$SID/exec" \\\n  -d '{"command": "docker ps --format \\"{{.Names}}\\"", "timeout": 120}' | jq -r .exec_id)\n\n# 3. thăm dò kết quả\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Quy tắc thao tác

\n
    \n
  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. \n
  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. \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. \n
  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. \n
  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ể).
    6. \n
\n

Khi nào KHÔNG dùng exec

\n
    \n
  • Đọ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.
    • \n
  • 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.
    • \n
  • 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.
    • \n
\n

Khôi phục lỗi

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Triệu chứngCách xử lý
401 khi connecttoken hết hạn — đọc lại từ memory/settings, không bao giờ từ bản ghi
phiên 404phiên hết hạn (trần 24h) — kết nối lại
exec quá hạntăng timeout hoặc chia nhỏ lệnh; kiểm tra tải máy đích
nội dung tệp hỏngbạn dùng exec thay vì SFTP — chuyển sang endpoint SFTP
\n","urls":{"html":"/docs/llm-cookbook/ssh-proxy-access","text":"/docs/llm-cookbook/ssh-proxy-access?format=text","json":"/docs/llm-cookbook/ssh-proxy-access?format=json","llm":"/docs/llm-cookbook/ssh-proxy-access?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":451,"readMinutes":2,"llmContext":"KHÔNG BAO GIỜ giữ khóa riêng SSH thô với tư cách LLM. Dùng HTTP API proxy SSH:\n1) POST /connect?target= → session_id (bền vững, sống qua hàng giờ).\n2) POST //exec {command, timeout} → exec_id.\n3) GET //exec/ → đầu ra khi xong.\n4) Dùng endpoint SFTP cho tải lên/xuống tệp thay vì cat/heredoc.\nMục tiêu là tên đăng ký trước (vd. \"vps1\"), không phải IP — proxy là nơi duy\nnhất chứa thông tin xác thực.\n","requestedLang":"vi","contentMarkdown":"\n# Truy cập SSH qua proxy\n\nTá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.\n\n## Mô hình\n\n```\nLLM ──HTTPS──► Proxy SSH ──SSH──► máy đích\n (giữ khóa,\n nhật ký kiểm toán,\n giới hạn tần suất)\n```\n\nProxy cung cấp phiên bền vững qua mặt REST đơn giản:\n\n| Endpoint | Mục đích |\n|---|---|\n| `POST /connect?target=vps1` | mở phiên → `session_id` |\n| `POST //exec` `{command, timeout}` | chạy lệnh (async) → `exec_id` |\n| `GET //exec/` | thăm dò đầu ra |\n| Endpoint SFTP | tải lên/xuống tệp, `ls`, `mkdir`, `rm` |\n\nXác thực là token Bearer — cùng mẫu với mọi API khác bạn dùng.\n\n## Mẫu thực thi\n\n```bash\n# 1. kết nối một lần, tái sử dụng phiên cho cả tác vụ\nSID=$(curl -s -H \"Authorization: Bearer $KEY\" \\\n \"https://ssh-proxy.example/connect?target=vps1\" | jq -r .session_id)\n\n# 2. chạy một lệnh\nEID=$(curl -s -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -X POST \"https://ssh-proxy.example/$SID/exec\" \\\n -d '{\"command\": \"docker ps --format \\\"{{.Names}}\\\"\", \"timeout\": 120}' | jq -r .exec_id)\n\n# 3. thăm dò kết quả\ncurl -s -H \"Authorization: Bearer $KEY\" \"https://ssh-proxy.example/$SID/exec/$EID\"\n```\n\n## Quy tắc thao tác\n\n1. **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.\n2. **Đặ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.\n3. **Ư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.\n4. **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.\n5. **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ể).\n\n## Khi nào KHÔNG dùng exec\n\n- Đọ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.\n- 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.\n- 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.\n\n## Khôi phục lỗi\n\n| Triệu chứng | Cách xử lý |\n|---|---|\n| 401 khi connect | token hết hạn — đọc lại từ memory/settings, không bao giờ từ bản ghi |\n| phiên 404 | phiên hết hạn (trần 24h) — kết nối lại |\n| exec quá hạn | tăng `timeout` hoặc chia nhỏ lệnh; kiểm tra tải máy đích |\n| nội dung tệp hỏng | bạn dùng `exec` thay vì SFTP — chuyển sang endpoint SFTP |\n","contentHtml":"

Truy cập SSH qua proxy

\n

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.

\n

Mô hình

\n
LLM ──HTTPS──► Proxy SSH ──SSH──► máy đích\n                (giữ khóa,\n                 nhật ký kiểm toán,\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:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointMục đích
POST /connect?target=vps1mở 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 SFTPtải lên/xuống tệp, ls, mkdir, rm
\n

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

\n

Mẫu thực thi

\n
# 1. kết nối một lần, tái sử dụng phiên cho cả tác vụ\nSID=$(curl -s -H "Authorization: Bearer $KEY" \\\n  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)\n\n# 2. chạy một lệnh\nEID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \\\n  -X POST "https://ssh-proxy.example/$SID/exec" \\\n  -d '{"command": "docker ps --format \\"{{.Names}}\\"", "timeout": 120}' | jq -r .exec_id)\n\n# 3. thăm dò kết quả\ncurl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"

Quy tắc thao tác

\n
    \n
  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. \n
  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. \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. \n
  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. \n
  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ể).
    6. \n
\n

Khi nào KHÔNG dùng exec

\n
    \n
  • Đọ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.
    • \n
  • 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.
    • \n
  • 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.
    • \n
\n

Khôi phục lỗi

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Triệu chứngCách xử lý
401 khi connecttoken hết hạn — đọc lại từ memory/settings, không bao giờ từ bản ghi
phiên 404phiên hết hạn (trần 24h) — kết nối lại
exec quá hạntăng timeout hoặc chia nhỏ lệnh; kiểm tra tải máy đích
nội dung tệp hỏngbạn dùng exec thay vì SFTP — chuyển sang endpoint SFTP
\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}