kasm

KASM Workspaces

关键：密钥和 .env

• 切勿将有效的 .env 文件或凭据存放在任何技能文件夹中。
• .env.template 文件只能放在技能中的 assets/ 目录下。
• 将有效密钥存储在 ~/.admin/.env 中，并从该处引用。

用途：在 Linux 服务器上安装、配置、管理和排查 KASM Workspaces 问题。

步骤 0：确定用户的需求

询问用户需要哪方面的帮助：

任务	参考资料
全新安装	references/installation.md
工作区配置（配置文件、卷、Docker 覆盖项）	references/workspace-configuration.md
排查错误	references/troubleshooting.md
备份和恢复	references/backup-recovery.md
Cloudflare Tunnel 或反向代理	references/networking.md
数据库查询或维护	references/database-operations.md
API 调用或自动化	references/api-reference.md
服务管理（启动/停止/日志）	references/service-management.md

阅读相应的参考文件并遵循其中的说明。

---

快速参考

系统要求

• Docker >= 25.0.5，Docker Compose >= 2.40.2
• 最低配置：2 核、4GB RAM、75GB SSD
• 每个会话默认需要：2,768MB RAM + 2 核
• 强烈建议使用 Swap 分区
• 支持的系统：Ubuntu 22.04/24.04、Debian 11/12、RHEL 8/9/10、Oracle Linux 8/9、AlmaLinux/Rocky 8/9、Raspberry Pi OS 11/12
• 架构：amd64 和 arm64

关键路径

路径	用途
/opt/kasm/current/	安装根目录
/opt/kasm/current/bin/start	启动所有服务
/opt/kasm/current/bin/stop	停止所有服务
/opt/kasm/current/log/	日志文件（原始格式 + JSON）
/mnt/kasm_profiles/	持久化配置文件（卷挂载）
/var/lib/docker	Docker 存储

关键容器

容器	角色
kasm_api	API 服务
kasm_agent	Agent（运行工作区容器）
kasm_manager	Manager（编排）
kasm_proxy	HTTPS 代理
kasm_db	PostgreSQL 数据库（用户：kasmapp，数据库：kasm）

服务控制

sudo /opt/kasm/current/bin/stop     # Stop all
sudo /opt/kasm/current/bin/start    # Start all
sudo docker restart kasm_api        # Restart single service
sudo docker logs -f kasm_api        # Live logs

---

关键规则

• 始终先安装 Docker CE 和 Compose 插件，再安装 KASM。
• 始终配置 Swap；即使 RAM 充足，KASM 在没有 Swap 的情况下也可能不稳定。
• 每个并发会话需要约 2-4GB RAM。请据此配置服务器。
• 未配置 HTTPS 时，不要将端口 8443 暴露到公网。
• KASM API 使用 JSON 载荷进行身份验证（不是 HTTP Basic Auth）。参见 references/api-reference.md。
• API 将工作区称为“镜像”——使用 get_images，而不是 get_workspaces。
• 对于 S3 持久化配置文件，路径中始终包含 @endpoint。缺少它会导致过多的 API 调用。

相关技能

• devops：服务器清单和配置
• backblaze-b2：兼容 S3 的存储
• 服务商技能（oci、hetzner、contabo 等）：服务器设置
• cloudflare-worker-base：Cloudflare 集成

参考资料

• KASM 文档：https://kasmweb.com/docs/latest/
• KASM 新版文档：https://docs.kasm.com/
• KASM GitHub 问题：https://github.com/kasmtech/workspaces-issues
• KASM Docker 镜像：https://github.com/kasmtech