目录

Kasm Workspaces 生产级部署:容器化桌面与离线镜像实践

Kasm 1.19 + Docker + Nginx:从安装到 Chrome 会话、持久化与备份

我有两台比较重的笔记本,每天背来背去不太现实;轻便机器的性能又不够,尤其是同时开几十个网页、再跑几个实验环境的时候,内存很快见底。

与其在本地堆硬件,不如把桌面和应用放到 Homelab,用浏览器按需开一个容器化工作区。Kasm Workspaces 正好符合这个思路:每个会话是一个 Docker 容器,底层用 KasmVNC 把桌面串流到浏览器,支持多用户、组权限和 SSO。

本文记录的是 Kasm Workspaces 1.19.0 在 Debian 12 虚拟机上的完整部署过程。实验环境的 Docker Hub 访问被阻断,所以走的是离线服务镜像加本地工作区镜像的路线;Nginx 反向代理、Chrome 工作区、持久化 Profile 和数据库备份都做了实际验证,截图来自这套环境。

实测范围

实测:Kasm 1.19.0 离线安装、Nginx/WebSocket 反向代理、Chrome 工作区启动、持久化 Profile、数据库备份与恢复。

未实测:SSO/OIDC 登录、跨版本升级、整机迁移、自定义镜像构建;这几节按官方文档整理,并在对应位置标注。

在看 Kasm 之前,我对比了几个远程桌面和浏览器隔离方案:

方案 协议 容器化 多用户 SSO 支持 自托管 许可证
Kasm Workspaces KasmVNC (WebSocket + WebRTC) 原生 Docker 支持 SAML / OIDC / LDAP 支持 Community 免费 / Enterprise 付费
Apache Guacamole RDP / VNC / SSH 需自行封装 支持 需插件 支持 Apache 2.0
Citrix Virtual Apps ICA / HDX K8s 支持 支持 完整 混合 商业
noVNC + Docker VNC over WebSocket 需自行封装 需自行实现 需自行实现 支持 MPL 2.0

Kasm 的优势在于把「容器生命周期」和「远程桌面」放在同一套平台里:用户点击工作区,平台在 Agent 上拉起对应镜像,会话结束容器销毁;管理员在后台统一管理镜像、用户、组和部署区域。

Community Edition 的限制
Kasm Workspaces Community Edition 免费,允许最多 5 个并发会话,定位是个人、非营利和非商业用途。超过 5 个并发会话,或者需要商业授权、审计、专属支持,就需要购买许可证。

Kasm 1.19 的单机部署由以下容器组成(没有 Redis):

graph TB
    subgraph Client["客户端"]
        Browser[浏览器]
    end

    subgraph Edge["边缘"]
        Nginx["Nginx<br/>TLS 终结 + WebSocket"]
    end

    subgraph Control["控制平面"]
        Proxy["kasm_proxy<br/>:8444"]
        API["kasm_api<br/>:8080 内部"]
        Manager["kasm_manager<br/>:8181 内部"]
        Guac["kasm_guac<br/>RDP/VNC/SSH 网关"]
        DB[(PostgreSQL<br/>kasm_db)]
    end

    subgraph Agent["Agent"]
        AgentSvc["kasm_agent<br/>:4444 内部"]
        Session["Chrome 会话容器<br/>userkasm.loc_*"]
    end

    Browser -->|"HTTPS + WSS"| Nginx
    Nginx -->|"proxy_pass :8444"| Proxy
    Proxy --> API
    API --> Manager
    Manager --> DB
    API --> Guac
    Manager -->|"调度"| AgentSvc
    AgentSvc -->|"创建/销毁"| Session

    style Browser fill:#64748b,color:#fff
    style Nginx fill:#059669,color:#fff
    style Proxy fill:#7c3aed,color:#fff
    style API fill:#7c3aed,color:#fff
    style Manager fill:#7c3aed,color:#fff
    style DB fill:#2563eb,color:#fff
    style AgentSvc fill:#d97706,color:#fff
    style Session fill:#be185d,color:#fff
组件 端口 职责
kasm_proxy 8444(可自定义) 对外提供 Web UI 和 KasmVNC 会话入口,监听 HTTPS
kasm_api 8080(容器内部) REST API、用户认证、会话请求
kasm_manager 8181(容器内部) 调度会话、管理 Agent、数据库日志
kasm_agent 4444(容器内部) 在宿主机上创建和销毁工作区容器
kasm_guac 内部 连接 RDP、VNC、SSH 服务器
kasm_db 5432(容器内部) PostgreSQL,保存用户、组、镜像、会话等元数据
RDP Gateway 3389 可选的 RDP 厚客户端入口

这里最容易混淆的是 kasm_proxy 和 Nginx 的关系:Nginx 负责对外的 443/9443,kasm_proxy 在内部监听 8444;Nginx 把所有请求(包括 WebSocket)转发给 kasm_proxy,再由它转发到 API 或会话。

实验环境
  • Debian 12 虚拟机,4 vCPU / 5.8 GiB 内存,额外 8 GiB swap
  • Docker 29.9.3,Docker Compose v5.7.1
  • Kasm Workspaces 1.19.0(离线服务镜像)
  • Nginx 1.22.1,监听 9443,自签证书
  • 443 端口预留给其他服务,8443 被 step-ca 占用,所以 Kasm 用 8444
  • Chrome 工作区镜像约 6.67 GB,单个会话实测占用约 540 MiB

Kasm 官方的最低要求是 2 核、4 GB 内存、75 GB 磁盘,Docker >= 28.5.2,Docker Compose >= 2.40.2。75 GB 主要是给默认工作区镜像留的空间;如果只加载一两个自定义镜像,实际占用会小很多。

资源 最低要求 本次实验
CPU 2 核 4 vCPU
内存 4 GB 5.8 GiB + 8 GiB swap
磁盘 75 GB 79 GB(装完后剩余约 38 GB)
Docker >= 28.5.2 29.9.3
Docker Compose >= 2.40.2 v5.7.1
并发会话不只受许可证限制

Community Edition 允许 5 个并发会话,但 Agent 是按宿主资源计算槽位的。实验环境里 Zone 显示 2 核 / 3.3 GiB,一个 2 核 / 2.7 GiB 的 Chrome 工作区就占满了槽位,第二个会话会报 No Agent slots available。

要跑更多会话,需要在 Infrastructure -> Docker Agents -> Edit 里调整 Agent 的 Cores Override 和 Memory Override,或者降低工作区的 Cores/Memory。不要只盯着 5 个许可证名额。

端口 用途
9443(实验)/ 443(生产) Nginx,对外提供 HTTPS
8444 kasm_proxy,供 Nginx 转发;生产环境用防火墙限制为仅本机可访问
3389 可选的 RDP Gateway,不需要就不要暴露
8080 / 8181 / 4444 / 5432 Kasm 容器内部通信,不映射到宿主机

如果服务器能访问 Docker Hub,安装脚本会自动拉取服务镜像。实验环境访问 Docker Hub 时连接被重置,所以用了 Kasm 官方提供的离线包:

  • kasm_release_service_images_amd64_1.19.0-latest.tar.gz:约 1.4 GB,加载后是 API、Manager、Agent、Guac、Proxy、PostgreSQL 和 RDP Gateway 等服务镜像,合计约 6.5 GB
  • kasm_release_logging_plugin_images_amd64_1.1-latest.tar.gz:约 34 MB,Docker 日志插件
  • kasm_network_plugin_images_amd64_1.5-latest.tar.gz:约 228 MB,本文用 --skip-egress 跳过,不需要

工作区镜像单独准备。本文用的是 kasmweb/chrome:1.19.0-rolling-daily,在能联网的机器上拉取后导出。拉取时显式指定 --platform linux/amd64,因为实验环境是 amd64;Chrome 这个 tag 目前没有 arm64 变体,ARM 主机要换成对应架构的镜像:

# 在能访问 Docker Hub 的机器上执行
docker pull --platform linux/amd64 kasmweb/chrome:1.19.0-rolling-daily
docker save kasmweb/chrome:1.19.0-rolling-daily | zstd -T0 -3 > kasm_chrome_image.tar.zst

把镜像包和安装包传到目标服务器后,先加载工作区镜像:

zstd -dc /tmp/kasm_chrome_image.tar.zst | sudo docker load
sudo docker images | grep kasmweb/chrome

从 Kasm 官网的 Downloads 页面获取当前版本。1.19.0 的安装包文件名是 kasm_release_1.19.0-latest.tar.gz:

cd /tmp
curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz
tar -xf kasm_release_1.19.0-latest.tar.gz

安装脚本的参数可以用 --help 查看。1.19 里比较关键的几个:

参数 作用
-L, --proxy-port kasm_proxy 的监听端口,默认 443
-e, --accept-eula 接受 EULA
-P, --admin-password 管理员密码,不指定则随机生成
-U, --user-password 普通用户密码,不指定则随机生成
-J, --swap-size 自动创建指定大小的 swap
-s, --offline-service 离线服务镜像包
--offline-logger-plugin 离线日志插件包
--skip-egress 不安装 egress 网络插件
--skip-v4l2loopback 跳过 v4l2loopback
--ignore-dep-failures 可选依赖失败时继续
-f, --use-static-images 使用静态版本工作区镜像
-W, --default-images 下载默认工作区镜像
不要额外加 -W
不加 -W 时安装脚本不会下载几十 GB 的默认工作区镜像,只安装服务。本文后来又单独加载了 Chrome 镜像,并手动在后台注册工作区。安装脚本里还有一个隐藏的 --no-images,但正常情况下用不到。
cd /tmp
sudo bash kasm_release/install.sh \
  --install-profile noninteractive \
  --accept-eula \
  --proxy-port 8444 \
  --swap-size 8192 \
  --offline-service /tmp/kasm_release_service_images_amd64_1.19.0-latest.tar.gz \
  --offline-logger-plugin /tmp/kasm_release_logging_plugin_images_amd64_1.1-latest.tar.gz \
  --skip-egress \
  --skip-v4l2loopback \
  --ignore-dep-failures

如果不指定 -P / -U,安装结束时会打印管理员和普通用户的初始密码,记得保存。安装过程中会创建 /opt/kasm/1.19.0、注册 systemd 服务,并把 Docker 日志插件装好。

安装脚本会重启 Docker
实验环境里安装脚本在配置日志插件时重启了 Docker Engine,已有的容器(包括同机的 Umami)被重启了一次。生产环境不要在承载其他关键容器的宿主机上直接跑安装脚本,至少先安排维护窗口。

安装完成后检查容器和 systemd 服务:

sudo systemctl status kasm --no-pager
sudo docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

正常情况下会看到:

kasm_db                  kasmweb/postgres:1.19.0-rolling          Up (healthy)
kasm_api                 kasmweb/api:1.19.0-rolling               Up (healthy)
kasm_manager             kasmweb/manager:1.19.0-rolling           Up (healthy)
kasm_agent               kasmweb/agent:1.19.0-rolling             Up (healthy)
kasm_guac                kasmweb/kasm-guac:1.19.0-rolling         Up (healthy)
kasm_proxy               kasmweb/proxy:1.19.0-rolling             Up
kasm_rdp_gateway         kasmweb/rdp-gateway:1.19.0-rolling       Up (healthy)
kasm_rdp_https_gateway   kasmweb/rdp-https-gateway:1.19.0-rolling Up (healthy)

刚启动时 kasm_api 和 kasm_manager 会先做数据库初始化,kasm_rdp_https_gateway 可能在 API 健康之前反复重启,日志里出现 Received HTML instead of JSON。等 API 健康后它会自己恢复,不需要手动干预。

浏览器打开 https://<服务器>:8444,用安装脚本输出的管理员账号登录。登录页的字段是 Email 和 Password,用户名是安装时生成的邮箱地址,不是 admin。

Kasm 登录页
Kasm Workspaces 1.19 登录页

登录后是管理后台仪表盘:

Kasm 管理后台
Kasm 管理后台仪表盘

仪表盘里的 Errors 是初始化阶段 RDP HTTPS Gateway 反复重启留下的历史记录;等 kasm_api 健康后它就不再增长。

Kasm 官方推荐把 kasm_proxy 放在 Nginx 后面。下面是对外 443、Kasm 监听 8444 的配置:

# /etc/nginx/sites-available/kasm.example.com
server {
    listen 80;
    listen [::]:80;
    server_name kasm.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name kasm.example.com;

    ssl_certificate     /etc/letsencrypt/live/kasm.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/kasm.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    # Kasm 上游会发送 HSTS;如果这里再加,响应里会出现两个头
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # 文件上传到会话时需要
    client_max_body_size 1G;

    location / {
        # Kasm 自己监听 HTTPS,所以这里必须是 https://
        proxy_pass https://127.0.0.1:8444;
        proxy_http_version 1.1;

        # KasmVNC 依赖 WebSocket
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # 必须和 Nginx 对外端口一致
        proxy_set_header X-Forwarded-Port 443;

        # 会话是长连接,超时时间要放大
        proxy_connect_timeout 1800s;
        proxy_send_timeout    1800s;
        proxy_read_timeout    1800s;

        # 串流场景必须关闭缓冲
        proxy_buffering off;
    }
}
实验环境:9443 与自签证书
实验环境的 443 被其他服务占用,Nginx 改听 9443,证书是自签的 kasm.homelab.internal(SAN 里同时包含 localhost 和 127.0.0.1)。这时 X-Forwarded-Port 要写 9443,Kasm Zone 里的 Proxy Port 也要写 9443,否则会话会去连错误端口。生产环境换成 443 和 Let’s Encrypt 即可,代理配置不变。
Nginx 1.25 及以后
listen 443 ssl http2 在新版本里会提示 http2 参数已废弃,改成 listen 443 ssl; 加一行 http2 on;。实验环境的 Nginx 1.22.1 仍使用旧写法。

启用并验证:

sudo ln -s /etc/nginx/sites-available/kasm.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

curl -sk https://127.0.0.1:8444/api/__healthcheck
# {"ok": true}
curl -sk -o /dev/null -w "%{http_code}\n" https://kasm.example.com/
# 200

实验环境里通过 9443 访问 Nginx 的实测结果:

Kasm 容器、健康检查、Nginx 与证书
容器状态、/api/__healthcheck、nginx -t 和证书信息的实测结果

Nginx 加好后,Kasm 还要知道自己的外部地址,否则会生成指向内部端口或内网地址的会话 URL。

进入 Infrastructure -> Deployment Zones -> Edit,重点看三项:

配置项 生产环境 实验环境
Proxy Hostname $request_host$ $request_host$
Proxy Port 443 9443
Upstream Auth Address 默认 proxy 通常可用 proxy
Proxy Port 必须和 Nginx 对外端口一致

这是我在实验环境里踩到的坑:Kasm 安装在 8444,Nginx 对外 9443,但 Zone 里的 Proxy Port 默认还是 8444。登录和后台都正常,点「启动会话」后 KasmVNC 却去连 https://localhost:8444,浏览器报 Connection Failed。把 Proxy Port 改成 9443 后会话立刻正常。

如果前面还有 SSO,Upstream Auth Address 和 OIDC 回调地址也要用外部地址,否则认证完成后可能跳回内网 IP。

先确认工作区镜像已经在宿主机上:

sudo docker images | grep kasmweb/chrome
# kasmweb/chrome   1.19.0-rolling-daily   6.67GB

进入 Workspaces -> Workspaces -> Add Workspace:

  1. Workspace Type 选择 Container
  2. Friendly Name 填 Chrome Browser
  3. Description 填一个用户能看懂的说明
  4. Docker Image 填 kasmweb/chrome:1.19.0-rolling-daily
  5. Cores 填 2,Memory 填 2.7,单位选 GiB
  6. CPU Allocation Method 选 Inherit
  7. Categories 填 Browsers
  8. 保存

Kasm 工作区列表
注册后的 Chrome Browser 工作区

保存后去 Access Management -> Groups -> All Users -> Workspaces 确认工作区已经分配给普通用户组。实验环境里新工作区会自动出现在 All Users 组;如果没有,手动点 Add Workspaces 加进去。

用普通用户登录,仪表盘会出现 Chrome Browser 卡片:

Kasm 用户仪表盘
普通用户仪表盘:Chrome Browser 工作区与会话缩略图

点击卡片,选择 Launch Session。Kasm 会在 Agent 上创建一个容器,容器名前缀是 userkasm.loc_,然后把 KasmVNC 流推到浏览器。下面是一个正在运行的 Chrome 会话:

Kasm Chrome 会话
通过 KasmVNC 在浏览器里运行 Chrome

在宿主机上可以看到会话容器:

sudo docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"
# userkasm.loc_<id>   kasmweb/chrome:1.19.0-rolling-daily   Up ...

实测这个 Chrome 会话占用约 540 MiB 内存,CPU 空闲时约 10%。控制平面(API、Manager、Agent、Guac、Proxy、PostgreSQL)合计约 1 GiB。

Kasm 默认的会话容器是临时的,关闭后数据丢失。要保留用户配置和文件,可以配置 Persistent Profile。

sudo mkdir -p /mnt/kasm_profiles
sudo chown 1000:1000 /mnt/kasm_profiles

1000 是 Kasm 会话容器内桌面用户的 UID(用户名 kasm-user)。

编辑 Chrome Browser 工作区,把 Persistent Profile Path 设为:

/mnt/kasm_profiles/{username}/{image_id}

路径模板里的 {username} 和 {image_id} 会展开成实际用户和镜像 ID。每个工作区的路径要唯一,避免不同镜像的配置文件互相覆盖。

保存后重新启动会话,启动对话框里会显示 Persistent Profile Enabled。Kasm 会把宿主目录直接 bind 到容器的 /home/kasm-user,可以用 docker inspect 确认:

sudo docker inspect userkasm.loc_<id> --format '{{json .Mounts}}'
# Source: /mnt/kasm_profiles/<user>/<image_id>
# Destination: /home/kasm-user

我在会话里创建了 persist-test.txt,关闭容器后重新启动,新会话里仍能看到这个文件;宿主目录里也能看到它。这说明 volume mount 模式的持久化是生效的。

Volume Profile 与 S3 Profile
本文用的是 volume mount 模式:宿主目录实时挂载进容器,没有额外的同步步骤。Kasm 还支持基于 S3 的 Profile Sync 和通用 Volume Mapping;如果用户分布在不同 Agent 上,或者需要集中存储,可以再考虑这些模式。

Kasm 的备份分三部分:PostgreSQL 数据库、/opt/kasm/current/conf 配置与证书、/mnt/kasm_profiles 用户数据。数据库是最关键的部分。

Kasm 的 PostgreSQL 容器里没有 postgres 角色,超级用户是 kasmapp:

sudo docker exec kasm_db pg_dump -U kasmapp -F t kasm > /tmp/kasm-backup.tar
ls -lh /tmp/kasm-backup.tar

实测这份备份约 8.6 MB(2 个用户、1 个工作区、1 条会话记录)。把它放进定时任务:

#!/usr/bin/env bash
# /opt/kasm-backup/backup.sh
set -euo pipefail

BACKUP_DIR="/opt/kasm-backup"
DATE=$(date +%Y%m%d_%H%M%S)
KASM_DIR=$(readlink -f /opt/kasm/current)
mkdir -p "${BACKUP_DIR}"

sudo docker exec kasm_db pg_dump -U kasmapp -F t kasm \
  > "${BACKUP_DIR}/kasm_db_${DATE}.tar"

# 用解析后的版本目录,避免 tar 只打包 current 这个符号链接
sudo tar czf "${BACKUP_DIR}/kasm_conf_${DATE}.tar.gz" \
  "${KASM_DIR}/conf" "${KASM_DIR}/certs"

find "${BACKUP_DIR}" -name 'kasm_db_*.tar' -mtime +30 -delete
find "${BACKUP_DIR}" -name 'kasm_conf_*.tar.gz' -mtime +30 -delete

用户 Profile 用 rsync 或文件系统快照单独备份:

sudo rsync -a /mnt/kasm_profiles/ /backup/kasm_profiles/

正式恢复前,先在一个临时数据库里验证备份可用:

sudo docker exec kasm_db psql -U kasmapp -d kasm \
  -c "DROP DATABASE IF EXISTS kasm_restore_test;" \
  -c "CREATE DATABASE kasm_restore_test;"
sudo docker cp /tmp/kasm-backup.tar kasm_db:/tmp/kasm-backup.tar
sudo docker exec kasm_db pg_restore -U kasmapp -d kasm_restore_test \
  --no-owner --no-privileges /tmp/kasm-backup.tar
sudo docker exec kasm_db psql -U kasmapp -d kasm_restore_test \
  -tAc "select (select count(*) from users), (select count(*) from images), (select count(*) from kasms);"
# 2|1|1
sudo docker exec kasm_db psql -U kasmapp -d kasm \
  -c "DROP DATABASE kasm_restore_test;"

恢复到正式库的流程是:停止 Kasm 服务,启动 kasm_db,执行 pg_restore --clean --if-exists,再启动 Kasm。恢复前务必确认没有活跃会话。

本节未做跨版本升级实测
实验环境是全新安装,没有执行 1.18 → 1.19 的跨版本升级,也没有做整机迁移;下面的命令和顺序来自官方 1.19 文档。正式操作前请先在测试环境验证数据库迁移,并准备好快照或备份作为回滚点。

升级前先备份数据库和配置,并确认没有活跃会话。1.19 的升级脚本是 upgrade.sh:

cd /tmp
tar -xf kasm_release_<新版本>.tar.gz
sudo bash kasm_release/upgrade.sh --proxy-port 8444

离线环境需要同时传入 --offline-service 和 --offline-logger-plugin。1.19 默认使用 rolling 服务镜像;如果希望固定版本,安装或升级时加 -f(静态镜像),或者用 -F 指定带日期的 rolling tag。升级完成后检查:

sudo systemctl status kasm --no-pager
sudo docker ps --format "table {{.Names}}\t{{.Status}}"
curl -sk https://127.0.0.1:8444/api/__healthcheck

迁移到新服务器时,保持 Kasm 版本一致,按这个顺序操作:

  1. 源服务器停止 Kasm,备份数据库、/opt/kasm/current/conf、证书和 /mnt/kasm_profiles
  2. 目标服务器安装相同版本的 Kasm,先不要导入旧数据库
  3. 恢复数据库和配置,把 Profile 目录同步过去
  4. 更新 Deployment Zone 的 Proxy Hostname / Proxy Port,有 SSO 时同步更新回调地址
  5. 启动 Kasm,验证登录、工作区和会话

如果只是换 IP、域名不变,主要改 DNS 和 Zone;如果域名也变了,证书、Nginx、OIDC 回调都要一起改。

Kasm 1.19 的 OIDC 配置在 Access Management -> Authentication -> OpenID -> Add Config。以 Authentik 为例,关键字段是:

字段 示例
Display Name Authentik
Hostname kasm.example.com(只填主机名,不带 https://)
Client ID / Secret Authentik Provider 生成
Authorization URL https://auth.example.com/application/o/authorize/
Token URL https://auth.example.com/application/o/token/
User Info URL https://auth.example.com/application/o/userinfo/
Scope 一行一个:openid、email、profile
Username Attribute preferred_username
Groups Attribute groups
Redirect URL https://kasm.example.com/api/oidc_callback

Authentik 侧创建 OAuth2/OpenID Provider 和 Application,Redirect URI 填上面的回调地址。组映射在 Access Management -> Groups -> 对应组 -> SSO Group Mappings 里添加,不是在 OIDC 配置里写 JSON。

本节未做端到端实测
实验环境没有部署 Authentik,这一节是按 Kasm 1.19 文档整理的配置步骤,没有做完整的 OIDC 登录验证。真正接入前,先用 curl 检查 OIDC Discovery 和 Token 端点,再从 Kasm 登录页确认回调地址。

Kasm 的自定义镜像基于 core image 构建,1.19 推荐从 kasmweb/core-ubuntu-jammy:1.19.0-rolling-daily 开始。一个示例 Dockerfile:

FROM kasmweb/core-ubuntu-jammy:1.19.0-rolling-daily
USER root

ENV HOME /home/kasm-user
ENV STARTUPDIR /dockerstartup
ENV INST_SCRIPTS $STARTUPDIR/install
WORKDIR $HOME

######### Customize Container Here ###########

RUN apt-get update && apt-get install -y --no-install-recommends \
    git vim tmux htop fonts-noto-cjk \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

######### End Customizations ###########

RUN chown 1000:0 $HOME
RUN $STARTUPDIR/set_user_permission.sh $HOME
USER 1000

构建后在 Workspaces -> Add Workspace 里把 Docker Image 填成自己的镜像名。Kasm 不会自动使用 latest,必须写明确的 tag。

1. 启动会话报 No Agent slots available

不是许可证问题,而是 Agent 资源槽位不够。检查 Infrastructure -> Docker Agents 里 Agent 的可用 Cores/Memory,以及工作区配置的 Cores/Memory。实验环境 2 核 / 2.7 GiB 的工作区只能跑一个;要并行跑多个,调整 Agent 的 Cores/Memory Override,或降低工作区资源。

2. 登录正常,启动会话报 Connection Failed

先看 Zone 的 Proxy Port 是否等于 Nginx 对外端口。我们遇到的是 Zone 仍为 8444、Nginx 对外 9443,KasmVNC 去连 8444 导致失败。改成 9443 后恢复。

3. 离线安装时镜像加载失败

确认 --offline-service 指向的是 Kasm 的服务镜像包,不是安装包;工作区镜像要单独 docker load。如果服务器访问不了 Docker Hub,安装脚本不会自动拉取工作区镜像,需要在后台手动注册本地镜像。

4. kasm_rdp_https_gateway 反复重启

API 未就绪时它会报 Received HTML instead of JSON,等 kasm_api 健康后会自动恢复。如果几分钟后仍在重启,检查 kasm_api 日志和数据库连接。

5. Nginx 返回 502

先直接访问 https://127.0.0.1:8444/api/__healthcheck。如果 8444 正常而 Nginx 502,检查 proxy_pass 是否写成 https://、proxy_ssl_verify 是否拦截了自签证书,以及 Nginx 是否能访问 127.0.0.1:8444。

6. 响应头里出现两个 HSTS

Nginx 和 Kasm 上游都加了 HSTS 时会出现重复头。保留一层即可,避免重复。

# 服务状态
sudo systemctl status kasm --no-pager

# 容器状态
sudo docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

# 健康检查
curl -sk https://127.0.0.1:8444/api/__healthcheck

# 资源占用
sudo docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

# 查看 API 日志
sudo docker logs kasm_api 2>&1 | tail -50

# 重启 Kasm
sudo systemctl restart kasm
  • 只暴露 Nginx 的 443(实验环境 9443),不要暴露 8444、8080、8181、4444、5432
  • 不需要 RDP 时不要发布 3389
  • 修改安装时生成的默认密码,管理员和普通用户都要改
  • 生产环境把 Nginx 的证书换成受信任证书;如果还要直连 Kasm 或让 Nginx 校验上游,再用受信任证书替换 Kasm 自签证书,路径是 /opt/kasm/current/certs/kasm_nginx.crt 和 kasm_nginx.key
  • Community Edition 只允许非商业用途和最多 5 个并发会话
  1. 阅读 Kasm 1.19 Release Notes
  2. 备份数据库、配置和 Profile
  3. 确认没有活跃会话
  4. 下载新版本安装包和对应的离线镜像包
  5. 执行 upgrade.sh,观察数据库迁移和容器启动
  6. 检查 /api/__healthcheck、登录、工作区和实际会话