Tài liệu

Bắt đầu nhanh + mô tả chức năng của từng phần, từng thiết bị (đang tiếp tục cập nhật)

Kiến trúc & Tech Stack của SSH Everywhere

> Bài viết này giải thích kiến trúc tổng thể, các giao thức và tech stack của SSH Everywhere theo cách dễ hiểu. Dành cho những ai muốn biết「nó thực sự hoạt động như thế nào」, không cần nền tảng kỹ thuật cũng đọc hiểu được.

---

Hiểu toàn bộ dự án trong một câu

SSH Everywhere là một bảng điều khiển vận hành từ xa máy chủ / thiết bị tất cả trong một, sánh ngang 1Panel / BT Panel. Năng lực cốt lõi của nó là: dù thiết bị của bạn nằm ở góc nào của mạng — có IP công cộng, không có IP công cộng (sau NAT), hay thậm chí là điện thoại Android — đều có thể quản lý nó từ một bảng điều khiển này giống như dùng SSH.

Bản thân bảng điều khiển được triển khai trên một máy chủ có IP công cộng (lắng nghe 0.0.0.0:5501). Bạn truy cập bảng điều khiển qua trình duyệt, bảng điều khiển lại thông qua các「cách kết nối」khác nhau để tiếp cận từng thiết bị đích.

---

Kiến trúc tổng thể (nhìn một hình là hiểu)

┌─────────────────────────────────────────────────────────────┐
│  Frontend trình duyệt (ứng dụng một trang, mô phỏng OS desktop) │
│  Cửa sổ desktop · Thanh tác vụ · Menu bắt đầu · Bảng điều khiển │
│  · Terminal thật · Thư viện biểu tượng · JS thuần (không framework) │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP REST + SocketIO
┌──────────────────────────┴──────────────────────────────────┐
│  Backend bảng điều khiển (Flask + Flask-SocketIO, Python)    │
│  Chương trình chính · Máy chủ đường hầm ngược · Máy chủ SocketIO │
│  · Truyền tệp · Bảo vệ chống sập · Quản lý trang web          │
│  · Sao lưu · Cơ sở dữ liệu SQLite                            │
└───┬───────────────┬──────────────────┬──────────────────────┘
    │ SSH           │ Đường hầm ngược   │ SocketIO
    │ trực tiếp/qua đường hầm │ (0.0.0.0:4433) │ (qua HTTP)
    ▼                ▼                  ▼
┌────────┐    ┌──────────────┐    ┌─────────────────┐
│ Có IP  │    │ Linux không  │    │ Điện thoại      │
│ công cộng │ │ có IP công   │   │ Android         │
│        │    │ cộng/NAS/Pi  │    │ (Termux)        │
└────────┘    └──────────────┘    └─────────────────┘

---

Bốn cách kết nối (giao thức)

SSH Everywhere sử dụng nội bộ 4 giao thức, mỗi loại có phân công riêng, hướng tới các loại thiết bị khác nhau:

1. SSH —— kênh chủ lực

Công dụng: các chức năng cốt lõi để quản lý mọi「máy chủ Linux thông thường」.

  • Quản lý hệ thống (tổng quan, tiến trình, tác vụ định kỳ, tường lửa, Docker, trang web, nguồn image, bảo vệ chống sập)
  • Terminal (shell tương tác)
  • Quản lý tệp (tải lên/tải xuống/chỉnh sửa/nén)
  • Kiểm tra tình trạng (CPU/bộ nhớ/ổ đĩa/nhiệt độ)
  • Thực thi lệnh

Cách kết nối:

  • Có IP công cộng: bảng điều khiển kết nối trực tiếp host:port
  • Không có IP công cộng: bảng điều khiển trước tiên tạo một cổng proxy cục bộ qua đường hầm ngược, rồi kết nối SSH tới đó

> Nói cách khác, bản chất của đường hầm ngược là「đưa SSH tới những thiết bị không có IP công cộng」, nên SSH là giao thức điểm đến cuối cùng.

2. Giao thức đường hầm ngược —— kênh xuyên NAT

Công dụng: giúp「thiết bị không có IP công cộng」có thể được bảng điều khiển tiếp cận. Phía thiết bị chủ động「kết nối ra」tới bảng điều khiển, thiết lập một kết nối TCP ngược dài hạn; bảng điều khiển gửi lệnh và chuyển tiếp cổng qua đường hầm này.

Đặc điểm: kết nối TCP dài hạn + mã hóa (AES-256-GCM), máy chủ lắng nghe 0.0.0.0:4433.

Tình huống điển hình:

  • Vận hành xuyên NAT qua SSH cho máy chủ Linux không có IP công cộng (trong đường hầm lại chạy SSH)
  • Xuyên cổng: ánh xạ cổng dịch vụ trên thiết bị (như 8090) sang cổng công cộng của bảng điều khiển

> Khái niệm dễ nhầm: chuyển tiếp cổng vs xuyên cổng

>

> | | Chuyển tiếp cổng | Xuyên cổng |

> |---|---|---|

> | Thiết bị áp dụng | Máy chủ có IP công cộng | Thiết bị xuyên NAT không có IP công cộng |

> | Cách thực hiện | DNAT của tường lửa hệ thống, làm ngay trên máy chủ đích | Đi qua đường hầm ngược |

> | Luồng dữ liệu | Người truy cập → IP công cộng đích → cổng đích | Người truy cập → cổng công cộng của bảng điều khiển → đường hầm ngược → cổng thiết bị |

> | Phụ thuộc thiết bị trực tuyến | Không phụ thuộc | Có phụ thuộc (thiết bị phải giữ Agent trực tuyến) |

>

> Một câu: 「Chuyển tiếp」dành cho máy chủ có IP công cộng; 「Xuyên cổng」dành cho thiết bị không có IP công cộng.

3. SocketIO —— kênh riêng cho điện thoại Android

Công dụng: quản lý Termux trên điện thoại Android. NAT của mạng di động thay đổi liên tục, SSH không ổn định, nên dùng kênh long-polling ổn định SocketIO (giải pháp trưởng thành đã được kiểm chứng trên máy thật).

Agent chạy trên điện thoại cung cấp qua SocketIO:

  • Quản lý hệ thống (tổng quan/tiến trình/tác vụ định kỳ)
  • Terminal (cầu nối PTY)
  • Quản lý tệp
  • Giám sát tình trạng (báo cáo mỗi 30 giây: tải/bộ nhớ/ổ đĩa/pin/nhiệt độ)

> Đây là kênh duy nhất「không đi qua SSH」 trong dự án — vì điện thoại Android không dùng sshd mà đi qua kết nối dài SocketIO.

4. HTTP REST —— giữa frontend và backend

Frontend trình duyệt gọi backend bảng điều khiển qua REST API, đồng thời dùng SocketIO cho giao tiếp hai chiều thời gian thực như terminal.

---

Bảng tổng hợp đường tiếp cận ba loại thiết bị

Loại thiết bịCách kết nốiGiao thức điểm đến cuối cùngMô tả
Máy chủ Linux có IP công cộngBảng điều khiển kết nối trực tiếpSSHTình huống trực tiếp nhất
Máy chủ Linux không có IP công cộng (NAS/Raspberry Pi...)Đường hầm ngược tạo proxy → SSHSSH (được vận chuyển qua đường hầm)Đường hầm là「người vận chuyển」của SSH
Điện thoại Android (Termux)Long-polling SocketIOSocketIO (duy nhất không dùng SSH)Kênh ổn định riêng cho điện thoại

---

Lưu trữ dữ liệu

  • Cơ sở dữ liệu SQLite (data/ssheverywhere.db): thẻ máy chủ, chuyển tiếp cổng, bản ghi xuyên NAT, người dùng, tác vụ...
  • Hệ thống tệp: tệp sao lưu, khóa đường hầm, tài nguyên tĩnh.

---

Hình thức triển khai

  • Bảng điều khiển: dịch vụ systemd ssh-everywhere.service, lắng nghe 0.0.0.0:5501.
  • Đường hầm ngược: lắng nghe 0.0.0.0:4433.
  • Agent trên thiết bị đích thường trú dưới dạng dịch vụ (Linux dùng systemd / Termux dùng termux-services).

---

Về tên dự án「SSH Everywhere」

Tên dự án là SSH Everywhere, mang ý nghĩa「giống như SSH, quản lý được ở mọi nơi」. SSH là cách kết nối chủ lực tuyệt đối của toàn bộ dự án: ngoài một kịch bản nhỏ là điện thoại Android, tất cả các chức năng còn lại (quản lý máy chủ Linux, vận hành xuyên NAT, truyền tệp, kiểm tra tình trạng) cuối cùng đều dừng ở SSH. Và bản chất của đường hầm ngược cũng chính là「đưa SSH tới mọi nơi」. Vì vậy cái tên「SSH Everywhere」đã thể hiện chính xác năng lực cốt lõi của dự án.