Services

Guacamole — remote desktop trên trình duyệt— browser remote desktop

Admin bấm một nút trên /vps/{id} là mở màn hình VPS ngay trong trình duyệt, có ghi audit. Trang này tách rõ phần đã chạy trong code, phần đã đổi so với bản thiết kế và phần vẫn chỉ là kế hoạch. One click on /vps/{id} opens the VPS desktop in the admin's browser, with an audit log. This page separates what is implemented in code, what changed from the design, and what is still only planned.

• Cập nhậtUpdated 29/09/2026
• NguồnSource monitor/GUACAMOLE_FEATURE_PLAN.md
• monitor/fxconsole/docker-compose.yml (guacd, guacamole)
• monitor/fxconsole/app/Http/Controllers/GuacamoleSessionController.php
• monitor/fxconsole/docker/nginx-guac/README.md

Đã làm và kế hoạchImplemented vs planned

Kiến trúc thực tếActual architecture

flowchart LR
  ADM(["Trình duyệt admin"]) -- "HTTPS" --> FX["fxconsole /vps/{id}"]
  FX -- "ghi audit" --> MY[("MySQL vps_remote_sessions")]
  FX -- "trả URL ?data=token (60 s)" --> ADM
  ADM -- "HTTPS + WebSocket (tab mới)" --> RP["Reverse proxy NPM / aaPanel (TLS)"]
  RP -- "HTTP" --> GC["guacamole :8080 (host :8282)"]
  GC -- "guac_internal :4822" --> GD["guacd"]
  GD -- "VNC :5900 tới lan_ip qua tunnel WireGuard" --> VPS["VPS Windows: TightVNC + phiên AutoLogon"]

flowchart LR
  ADM(["Admin browser"]) -- "HTTPS" --> FX["fxconsole /vps/{id}"]
  FX -- "write audit row" --> MY[("MySQL vps_remote_sessions")]
  FX -- "return URL ?data=token (60 s)" --> ADM
  ADM -- "HTTPS + WebSocket (new tab)" --> RP["Reverse proxy NPM / aaPanel (TLS)"]
  RP -- "HTTP" --> GC["guacamole :8080 (host :8282)"]
  GC -- "guac_internal :4822" --> GD["guacd"]
  GD -- "VNC :5900 to lan_ip through the WireGuard tunnel" --> VPS["Windows VPS: TightVNC + AutoLogon session"]

Luồng bấm ConnectThe Connect flow

1. Admin bấm Connect trên /vps/{id}; React gọi POST /admin/vps/{id}/remote-session.The admin clicks Connect on /vps/{id}; React calls POST /admin/vps/{id}/remote-session.
2. Server kiểm tra: phải là admin (403); đã cấu hình guac_json_secret_key và guac_public_url (503); secret đúng 32 ký tự hex = 16 byte (503); VPS đã báo lan_ip (422); có vnc_password và giải mã được (422).The server checks: admin only (403); guac_json_secret_key and guac_public_url configured (503); the secret is exactly 32 hex chars = 16 bytes (503); the VPS has reported lan_ip (422); vnc_password exists and decrypts (422).
3. Ghi dòng vps_remote_sessions (token_jti UUID, vps_id, admin_id, opened_at, IP, user agent).Insert a vps_remote_sessions row (token_jti UUID, vps_id, admin_id, opened_at, IP, user agent).
4. Dựng JSON: username = admin-{id}, expires = bây giờ + 60 s, một connection đặt tên theo tên VPS với protocol: vnc, hostname = lan_ip, port, password, color-depth: 24, clipboard hai chiều (disable-copy/paste: false).Build the JSON: username = admin-{id}, expires = now + 60 s, one connection named after the VPS with protocol: vnc, hostname = lan_ip, port, password, color-depth: 24, two-way clipboard (disable-copy/paste: false).
5. Ký + mã hoá theo đặc tả guacamole-auth-json rồi trả {url, jti} với url = <guac_public_url>/?data=<base64>.Sign + encrypt per the guacamole-auth-json spec, then return {url, jti} where url = <guac_public_url>/?data=<base64>.
6. Trình duyệt mở URL ở tab mới; Guacamole giải mã token, gọi guacd, vẽ desktop. Tải lại trang = bấm Connect lại = dòng audit mới.The browser opens the URL in a new tab; Guacamole decodes the token, dials guacd and renders the desktop. Reloading means a new Connect click and a new audit row.

signature = HMAC-SHA256(secret_bytes, json_string)
signed    = signature . json_string                  (raw byte concat)
encrypted = AES-128-CBC(secret_bytes, IV=zeros, signed)   (PKCS#7 padded)
token     = base64(encrypted)

Service trong docker-composeCompose services

guacd:
  image: guacamole/guacd:latest
  container_name: fxconsole-guacd
  networks: [guac_internal]
  restart: unless-stopped

guacamole:
  image: guacamole/guacamole:latest
  container_name: fxconsole-guacamole
  depends_on: [guacd]
  environment:
    GUACD_HOSTNAME: guacd
    GUACD_PORT: "4822"
    JSON_SECRET_KEY: ${GUAC_JSON_SECRET_KEY:-}
    WEBAPP_CONTEXT: ROOT
  networks: [guac_internal]
  ports:
    - "8282:8080"
  volumes:
    - guac_drive:/var/lib/guacamole/drive
  restart: unless-stopped

Cấu hình (chỉ tên key)Configuration (key names only)

Reverse proxyReverse proxy

Bước 1: cho NPM tới được containerStep 1: let NPM reach the container

docker network ls | grep guac
# fxconsole_guac_internal   bridge   local
docker network connect fxconsole_guac_internal nginx-proxy-manager_app_1

services:
  app:
    networks:
      - default
      - fxconsole_guac_internal
networks:
  fxconsole_guac_internal:
    external: true

Bước 2: tạo proxy host trong NPMStep 2: create the NPM proxy host

Bước 3: trỏ fxconsole tới URL mớiStep 3: point fxconsole at the new URL

Bước 4: kiểm traStep 4: verify

# 1. NPM reaches the upstream (inside the NPM container for Option 1A)
docker exec -it nginx-proxy-manager_app_1 sh
curl -I http://fxconsole-guacamole:8080
# Expect: HTTP/1.1 200 OK

# 2. End-to-end through NPM
curl -I https://guacamole.yourdomain.com
# Expect: 200 OK + strict-transport-security header

# 3. WebSocket upgrade
curl -i -N \
  -H "Connection: Upgrade" -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: dGVzdA==" -H "Sec-WebSocket-Version: 13" \
  -H "Origin: https://guacamole.yourdomain.com" \
  https://guacamole.yourdomain.com/websocket-tunnel
# Expect: HTTP/1.1 101 Switching Protocols

Không dùng NPM: aaPanel / nginx trên hostWithout NPM: aaPanel / host nginx

GUAC_DOMAIN=guacamole.yourdomain.com \
  envsubst '${GUAC_DOMAIN}' \
    < guacamole.conf.template \
    > /www/server/panel/vhost/nginx/guacamole.conf
nginx -t && nginx -s reload

Audit và dọn sessionAudit and session cleanup

docker exec fxconsole-app php artisan fxconsole:close-stale-remote-sessions --dry-run --hours=24

Xử lý sự cốTroubleshooting

Ghi chú bảo mậtSecurity notes

Kế hoạch còn lạiRemaining roadmap

Phase 2 — PolishPhase 2 — Polish PLANNED

Phase 3 — Chuẩn compliancePhase 3 — Compliance-grade PLANNED

Câu hỏi còn mởOpen questions