Scribbles for my bad memory

使用 Apache Guacamole 和 PopOS 搭建基于网页浏览器的无客户端远程桌面访问系统的完整指南。

概述

• Guacamole: 基于 Web 的远程桌面网关（HTML5，无需安装客户端软件）
• 目标系统: PopOS 配置 xrdp 服务器
• 访问方式: 任何设备通过浏览器访问
• 支持协议: RDP、VNC、SSH、Telnet、Kubernetes 连接

1. PopOS RDP 服务器配置

安装和配置 xrdp

# 安装 xrdp（比 GNOME 自带的远程桌面更稳定）
sudo apt update
sudo apt install xrdp

# 启动并设置开机自启
sudo systemctl enable xrdp
sudo systemctl start xrdp

# 验证服务状态
sudo systemctl status xrdp

解决 PolicyKit 权限问题

创建文件 /etc/polkit-1/localauthority/50-local.d/45-allow-colord.pkla：

[Allow Colord All Users]
Identity=unix-user:*
Action=org.freedesktop.color-manager.*
ResultAny=no
ResultInactive=no
ResultActive=yes

[Allow PackageKit All Users]
Identity=unix-user:*
Action=org.freedesktop.packagekit.*
ResultAny=no
ResultInactive=no
ResultActive=yes

可选：防火墙配置

# 如果使用 Docker 和局域网 IP，通常不需要开放端口
# 只有需要外部访问时才开放
sudo ufw allow 3389

2. Guacamole Docker 配置

更新的 Docker Compose 配置

services:
  guacdb:
    container_name: guacamoledb
    image: mariadb:10.11
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: 'MariaDBRootPass2024'
      MYSQL_DATABASE: 'guacamole_db'
      MYSQL_USER: 'guacamole_user'
      MYSQL_PASSWORD: 'MariaDBUserPass2024'
    volumes:
      - db-data:/var/lib/mysql
    networks:
      - guacamole-network

  guacd:
    container_name: guacd
    image: guacamole/guacd:1.6.0
    restart: unless-stopped
    networks:
      - guacamole-network

  guacamole:
    container_name: guacamole
    image: guacamole/guacamole:1.6.0
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      GUACD_HOSTNAME: "guacd"
      MYSQL_HOSTNAME: "guacdb"
      MYSQL_DATABASE: "guacamole_db"
      MYSQL_USER: "guacamole_user"
      MYSQL_PASSWORD: "MariaDBUserPass2024"
      TOTP_ENABLED: "true"
      WEBAPP_CONTEXT: "ROOT"  # 允许直接通过 http://localhost:8080 访问
    depends_on:
      - guacdb
      - guacd
    networks:
      - guacamole-network

networks:
  guacamole-network:
    driver: bridge

volumes:
  db-data:

数据库初始化

# 1. 创建目录并设置
mkdir guacamole
cd guacamole

# 2. 生成数据库初始化文件
docker run --rm guacamole/guacamole:1.6.0 /opt/guacamole/bin/initdb.sh --mysql > initdb.sql

# 3. 启动服务
docker-compose up -d

# 4. 等待数据库准备就绪
sleep 30

# 5. 导入数据库架构
docker exec -i guacamoledb mysql -u root -pMariaDBRootPass2024 guacamole_db < initdb.sql

# 6. 验证表已创建
docker exec -it guacamoledb mysql -u root -pMariaDBRootPass2024 -e "USE guacamole_db; SHOW TABLES;"

3. Guacamole 配置

初始设置

1. 访问 Guacamole：http://localhost:8080（注意：没有 /guacamole 后缀！）
2. 默认登录：guacadmin / guacadmin
3. 重要：立即更改默认密码

创建 RDP 连接

1. 前往 设置 → 连接 → 新建连接

2. 编辑连接：

   • 名称：PopOS 桌面（或任意名称）
   • 协议：RDP

3. 参数：

   • 主机名：使用实际局域网 IP（例如：192.168.1.100）
   • 端口：3389
   • 用户名：你的 PopOS 用户名
   • 密码：你的 PopOS 密码

4. 可选设置：

   • 安全模式：any 或 rdp
   • 忽略服务器证书：✓（勾选）
   • 禁用身份验证：✓（如果需要）

Guacamole 代理参数

• 通常保持空白（主机名、端口、加密字段）
• 只有在 guacd 运行在不同服务器时才需要配置

4. 关键网络配置说明

⚠️ Docker 网络注意事项

• 在连接主机名中使用 IP 地址，不要用域名
• 如果使用 Tailscale/VPN：使用物理网络 IP，不要用 VPN IP
• 容器 DNS 解析可能指向无法访问的网络
• Docker 可以通过局域网 IP 访问主机端口，无需防火墙规则

IP 地址查找示例

# 查找你的 PopOS IP
ip addr show | grep "inet 192"
# 在 Guacamole 连接中使用这个 IP，不要用 localhost 或域名

5. 测试

验证 RDP 服务

# 在 PopOS 上测试本地 RDP
telnet localhost 3389

测试 Guacamole 连接

1. 登录 Guacamole Web 界面
2. 点击你的连接
3. 应该能在浏览器中看到 PopOS 桌面

故障排除

常见问题

• PolicyKit 密码提示：添加上述 polkit 配置
• 黑屏：在本地popOS上退出登录

调试命令

# 检查 xrdp 状态
sudo systemctl status xrdp

# 检查端口监听
sudo netstat -tlnp | grep 3389

# 检查 Guacamole 日志
docker logs guacamole
docker logs guacd

# 重启 PolicyKit（如果需要）
sudo systemctl restart polkitd
# 或者简单重启
sudo reboot

生产环境增强

Nginx 反向代理（可选）

添加 HTTPS 和自定义域名访问，支持 WebSocket：

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
        access_log off;
    }
}

性能说明

• 优秀适用场景：办公工作、编程、系统管理
• 良好适用场景：局域网内一般桌面使用
• 不适合场景：高帧率游戏、视频播放
• 最佳环境：低延迟的本地网络

支持的协议

• RDP：Windows/Linux 远程桌面
• VNC：跨平台图形界面访问
• SSH：终端访问和文件传输
• Telnet：传统终端协议
• Kubernetes：容器编排访问

安全考虑

• 更改 Guacamole 默认密码 （问题不大，有二次验证）
• 使用 HTTPS（添加反向代理）

实用价值

通过这个配置，你可以：

• 在任何地方用任何设备（手机、平板、电脑）通过浏览器访问你的桌面
• 统一的 Web 入口管理所有远程连接
• 无需在每个设备安装各种客户端软件
• 搭建个人的"云工作台"

本配置已经在 PopOS 22.04 上通过测试

主要参考来源：

• Jeppson Tech Blog

A quick guide to set up clientless remote desktop access via web browser using Apache Guacamole and PopOS.

Overview

• Guacamole: Web-based remote desktop gateway (HTML5, no client software needed)
• Target: PopOS with xrdp server
• Access: Any device with a web browser
• Supports: RDP, VNC, SSH, Telnet, Kubernetes connections

1. PopOS RDP Server Setup

Install and Configure xrdp

# Install xrdp (more reliable than GNOME Remote Desktop)
sudo apt update
sudo apt install xrdp

# Start and enable service
sudo systemctl enable xrdp
sudo systemctl start xrdp

# Verify service
sudo systemctl status xrdp
sudo netstat -tlnp | grep 3389

Fix PolicyKit Permission Issues

Create /etc/polkit-1/localauthority/50-local.d/45-allow-colord.pkla:

[Allow Colord All Users]
Identity=unix-user:*
Action=org.freedesktop.color-manager.*
ResultAny=no
ResultInactive=no
ResultActive=yes

[Allow PackageKit All Users]
Identity=unix-user:*
Action=org.freedesktop.packagekit.*
ResultAny=no
ResultInactive=no
ResultActive=yes

Optional: Firewall Configuration

# Usually NOT needed if using Docker with LAN IP
# Only open if external access required
sudo ufw allow 3389

2. Guacamole Docker Setup

Updated Docker Compose Configuration

services:
  guacdb:
    container_name: guacamoledb
    image: mariadb:10.11
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: 'MariaDBRootPass2024'
      MYSQL_DATABASE: 'guacamole_db'
      MYSQL_USER: 'guacamole_user'
      MYSQL_PASSWORD: 'MariaDBUserPass2024'
    volumes:
      - db-data:/var/lib/mysql
    networks:
      - guacamole-network

  guacd:
    container_name: guacd
    image: guacamole/guacd:1.6.0
    restart: unless-stopped
    networks:
      - guacamole-network

  guacamole:
    container_name: guacamole
    image: guacamole/guacamole:1.6.0
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      GUACD_HOSTNAME: "guacd"
      MYSQL_HOSTNAME: "guacdb"
      MYSQL_DATABASE: "guacamole_db"
      MYSQL_USER: "guacamole_user"
      MYSQL_PASSWORD: "MariaDBUserPass2024"
      TOTP_ENABLED: "true"
      WEBAPP_CONTEXT: "ROOT"  # Access via http://localhost:8080
    depends_on:
      - guacdb
      - guacd
    networks:
      - guacamole-network

networks:
  guacamole-network:
    driver: bridge

volumes:
  db-data:

Database Initialization (Correct Method)

# 1. Create directory and setup
mkdir guacamole
cd guacamole

# 2. Generate database initialization file
docker run --rm guacamole/guacamole:1.6.0 /opt/guacamole/bin/initdb.sh --mysql > initdb.sql

# 3. Start services
docker-compose up -d

# 4. Wait for database to be ready
sleep 30

# 5. Import database schema (no docker cp needed!)
docker exec -i guacamoledb mysql -u root -pMariaDBRootPass2024 guacamole_db < initdb.sql

# 6. Verify tables created
docker exec -it guacamoledb mysql -u root -pMariaDBRootPass2024 -e "USE guacamole_db; SHOW TABLES;"

3. Guacamole Configuration

Initial Setup

1. Access Guacamole: http://localhost:8080 (note: no /guacamole suffix!)
2. Default login: guacadmin / guacadmin
3. Important: Change default password immediately

Create RDP Connection

1. Go to Settings → Connections → New Connection

2. Edit Connection:

   • Name: PopOS Desktop (or any name)
   • Protocol: RDP

3. Parameters:

   • Hostname: Use actual LAN IP (e.g., 192.168.1.100)
   • Port: 3389
   • Username: Your PopOS username
   • Password: Your PopOS password

4. Optional Settings:

   • Security mode: any or rdp
   • Ignore server certificate: ✓ (check)
   • Disable authentication: ✓ (if needed)

Guacamole Proxy Parameters

• Usually leave empty (Hostname, Port, Encryption fields)
• Only configure if guacd runs on different server

4. Critical Network Configuration Notes

⚠️ Docker Networking Gotchas

• Use IP addresses, not domain names in connection hostname
• If using Tailscale/VPN: Use physical network IP, not VPN IP
• Container DNS resolution may point to unreachable networks
• Docker can access host ports via LAN IP without firewall rules

Example IP Discovery

# Find your PopOS IP
ip addr show | grep "inet 192"
# Use this IP in Guacamole connection, not localhost or domain names

5. Testing

Verify RDP Service

# On PopOS, test local RDP
telnet localhost 3389

Test Guacamole Connection

1. Login to Guacamole web interface
2. Click your connection
3. Should see PopOS desktop in browser

Troubleshooting

Common Issues

• "Non-numeric character in element length": Version mismatch or network issue
• "Connection refused": Check xrdp service and firewall
• PolicyKit password prompts: Add polkit configuration above
• Black screen: Try different security mode settings
• Slow performance: Normal on high-latency networks, excellent on LAN

Debug Commands

# Check xrdp status
sudo systemctl status xrdp

# Check port listening
sudo netstat -tlnp | grep 3389

# Check Guacamole logs
docker logs guacamole
docker logs guacd

# Restart PolicyKit (if needed)
sudo systemctl restart polkitd
# Or simply reboot
sudo reboot

Production Enhancements

Nginx Reverse Proxy (Optional)

Add HTTPS and custom domain access:

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:8080;
		proxy_buffering off;
		proxy_http_version 1.1;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection $http_connection;
		access_log off;
    }
}

Performance Notes

• Excellent for: Office work, programming, system administration
• Good for: General desktop use on LAN
• Not ideal for: High-framerate gaming, video streaming
• Best on: Local network with low latency

Supported Protocols

• RDP: Windows/Linux remote desktop
• VNC: Cross-platform graphical access
• SSH: Terminal access with file transfer
• Telnet: Legacy terminal protocol
• Kubernetes: Container orchestration access

Security Considerations

• Change default Guacamole passwords
• Use HTTPS in production (add reverse proxy)
• Consider VPN access for external connections
• Regularly update Docker images
• PolicyKit configuration limits privilege escalation

Setup tested on PopOS 22.04 with Guacamole 1.6.0 via Docker

Key Sources:

• Jeppson Tech Blog
• Docker best practices and real-world testing