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
在看 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 上拉起对应镜像,会话结束容器销毁;管理员在后台统一管理镜像、用户、组和部署区域。
1.19 的组件
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 GBkasm_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 时安装脚本不会下载几十 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 日志插件装好。
安装完成后检查容器和 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。

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

仪表盘里的 Errors 是初始化阶段 RDP HTTPS Gateway 反复重启留下的历史记录;等 kasm_api 健康后它就不再增长。
Nginx 反向代理
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;
}
}
kasm.homelab.internal(SAN 里同时包含 localhost 和 127.0.0.1)。这时 X-Forwarded-Port 要写 9443,Kasm Zone 里的 Proxy Port 也要写 9443,否则会话会去连错误端口。生产环境换成 443 和 Let’s Encrypt 即可,代理配置不变。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 的实测结果:

修改 Deployment Zone
Nginx 加好后,Kasm 还要知道自己的外部地址,否则会生成指向内部端口或内网地址的会话 URL。
进入 Infrastructure -> Deployment Zones -> Edit,重点看三项:
| 配置项 | 生产环境 | 实验环境 |
|---|---|---|
Proxy Hostname |
$request_host$ |
$request_host$ |
Proxy Port |
443 |
9443 |
Upstream Auth Address |
默认 proxy 通常可用 |
proxy |
这是我在实验环境里踩到的坑:Kasm 安装在 8444,Nginx 对外 9443,但 Zone 里的 Proxy Port 默认还是 8444。登录和后台都正常,点「启动会话」后 KasmVNC 却去连 https://localhost:8444,浏览器报 Connection Failed。把 Proxy Port 改成 9443 后会话立刻正常。
如果前面还有 SSO,Upstream Auth Address 和 OIDC 回调地址也要用外部地址,否则认证完成后可能跳回内网 IP。
添加工作区
注册 Chrome 工作区
先确认工作区镜像已经在宿主机上:
sudo docker images | grep kasmweb/chrome
# kasmweb/chrome 1.19.0-rolling-daily 6.67GB
进入 Workspaces -> Workspaces -> Add Workspace:
- Workspace Type 选择
Container - Friendly Name 填
Chrome Browser - Description 填一个用户能看懂的说明
- Docker Image 填
kasmweb/chrome:1.19.0-rolling-daily - Cores 填
2,Memory 填2.7,单位选GiB - CPU Allocation Method 选
Inherit - Categories 填
Browsers - 保存

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

点击卡片,选择 Launch Session。Kasm 会在 Agent 上创建一个容器,容器名前缀是 userkasm.loc_,然后把 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 模式的持久化是生效的。
备份与恢复
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.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 版本一致,按这个顺序操作:
- 源服务器停止 Kasm,备份数据库、
/opt/kasm/current/conf、证书和/mnt/kasm_profiles - 目标服务器安装相同版本的 Kasm,先不要导入旧数据库
- 恢复数据库和配置,把 Profile 目录同步过去
- 更新 Deployment Zone 的
Proxy Hostname/Proxy Port,有 SSO 时同步更新回调地址 - 启动 Kasm,验证登录、工作区和会话
如果只是换 IP、域名不变,主要改 DNS 和 Zone;如果域名也变了,证书、Nginx、OIDC 回调都要一起改。
接入 SSO(可选)
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。
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 个并发会话
版本升级检查清单
- 阅读 Kasm 1.19 Release Notes
- 备份数据库、配置和 Profile
- 确认没有活跃会话
- 下载新版本安装包和对应的离线镜像包
- 执行
upgrade.sh,观察数据库迁移和容器启动 - 检查
/api/__healthcheck、登录、工作区和实际会话
参考资料
如果你觉得这篇文章对你有所帮助,欢迎赞赏~
赞赏