前置条件
- macOS 或 Windows：安装 Podman Desktop，并完成 Podman machine 初始化
- Linux 生产服务器：需要 sudo 权限、公网 IP 或域名，以及足够存放镜像和数据的磁盘
- 桌面 Podman machine 建议 6 GB 内存、20 GB 磁盘；Linux 生产建议至少 4 GB，推荐 8 GB
- 桌面本地默认使用 8080 端口；生产部署通常使用 80/443 端口
选择平台
macOS 和 Windows 是本地试用；Linux 是生产环境部署。
本地试用
在 macOS 上本地运行 kageos
适合在自己的 Mac 上先试用 kageos，还不需要准备 Linux 服务器。
安装并运行
安装 Podman Desktop，完成 Podman machine 初始化后运行 kageos。
$ brew install --cask podman-desktop
$ curl -fsSL https://kageos.com/install.sh | bash -s -- --port 8080
这条路径会做什么
- 运行 kageos 安装器前，先打开 Podman Desktop 并完成 Podman machine 初始化。
- 创建持久化的 kageos-data 数据卷，并运行 qiayanai/kageos 镜像。
- 首次安装成功后，安装器会输出 system 登录信息。
安装完成后
访问地址
http://localhost:8080
安装完成后，在这台 Mac 上打开这个地址。
用户名
system
首次启动时创建的内置管理员账号。
密码
kageos password
安装器会输出密码；这个命令可以再次查看。
本地试用
在 Windows 上本地运行 kageos
适合在 Windows 工作站上通过 PowerShell 先试用 kageos。
安装并运行
安装 Podman Desktop，完成 Podman machine 初始化后运行 kageos。
PS> winget install -e --id RedHat.Podman-Desktop
PS> iwr https://kageos.com/install.ps1 -OutFile install.ps1
PS> powershell -ExecutionPolicy Bypass -File .\install.ps1
这条路径会做什么
- Windows 上 Podman Desktop 会通过 Podman machine 运行 Linux 容器。
- 创建持久化的 kageos-data 数据卷，并运行 qiayanai/kageos 镜像。
- 首次安装成功后，安装器会输出 system 登录信息。
安装完成后
访问地址
http://localhost:8080
安装完成后，在 Windows 工作站上打开这个地址。
用户名
system
首次启动时创建的内置管理员账号。
密码
%USERPROFILE%\.kageos\bin\kageos.ps1 password
安装器会输出密码；这个命令可以再次查看。
生产环境部署
把 kageos 部署到 Linux 生产环境
适合让 kageos 跑在远程服务器上，给团队或长期环境使用。
生成 Linux 精确命令
先选一种生产部署路径，再复制生成出来的唯一命令。
生成的命令
只执行你选择路径生成的这一条命令。
$ curl -fsSL https://kageos.com/install-prod.sh | sudo bash -s -- --base-url https://app.example.com
中国大陆模式会优先使用阿里云镜像仓库，必要时再回退到 kageos 发布包下载通道和 DaoCloud 等公共镜像代理拉取公开依赖镜像。
默认安装
适用于中国大陆以外，或能正常拉取 DockerHub 镜像的服务器。
$ curl -fsSL https://kageos.com/install-prod.sh | sudo bash -s -- --base-url https://app.example.com
中国大陆服务器安装
只加 --cn，安装器会自动选择中国大陆可用的下载或拉取路径，必要时回源。
$ curl -fsSL https://kageos.com/install-prod.sh | sudo bash -s -- --base-url https://app.example.com --cn
先审查脚本再执行
需要安全审查或企业环境审核时，先下载查看，再执行安装器。
$ curl -fsSLO https://kageos.com/install-prod.sh
$ less install-prod.sh
$ sudo bash install-prod.sh --base-url https://app.example.com
彻底卸载清理
重装失败测试机前使用。--purge 会删除 /opt/kageos 数据。
$ curl -fsSL https://kageos.com/uninstall-prod.sh | sudo bash -s -- --yes --purge
这条路径会做什么
- 优先从国内镜像仓库拉取，必要时回退到发布包或上游镜像，并以 rootful all-in-one 容器方式运行。
- 默认把持久化数据放在 /opt/kageos/data；不会 clone 源码仓库。
- 只有中国大陆服务器需要 --cn；其他地区使用默认命令即可。
- --cn 也会把工作空间应用构建使用的 Go 模块下载切到国内更友好的代理配置。
- 服务器 IP 地址只适合首次验证；邀请真实用户前建议切到域名和 HTTPS。
- 如果宿主机 FORWARD 策略会拦截容器流量，安装器会为 kageos 公网端口添加范围更小的放行规则。
- 如果服务器本机能访问但公网仍打不开，先运行 sudo kageos doctor，并检查云防火墙规则。
- 需要强制重新拉镜像时，卸载脚本可以额外加 --remove-images。
- 自定义端口、固定镜像版本、容器引擎兜底等高级参数，可以在 install-prod.sh 里查看。
安装完成后
访问地址
你传入的 --base-url
安装完成后，用同一个地址打开 kageos。
用户名
system
生产环境初始化出来的管理员账号。
密码
sudo kageos password
用于再次查看生成的 system 密码。
排查
sudo kageos doctor
本机能访问但公网打不开时，先运行这个诊断。
部署了什么
L1
宿主机运行时
Linux 服务器上使用 rootful Podman 或 Docker，由安装器管理
L2
内置基础设施
all-in-one 镜像会在 kageos 容器内启动 MySQL、NATS 和 MinIO
L3
平台服务
Nginx、kageos API、Web UI、系统初始化和运行时服务
L4
应用运行时
生成的用户应用运行在平台运行时管理的隔离容器里
L5
持久化数据
生产配置、生成的密码、日志和服务数据卷都保存在你的服务器上
常用命令
# 查看状态
$ sudo kageos status
# 查看日志
$ sudo kageos logs
# 诊断公网访问
$ sudo kageos doctor
# 查看密码
$ sudo kageos password
# 升级
$ sudo kageos update
# 彻底卸载
$ curl -fsSL https://kageos.com/uninstall-prod.sh | sudo bash -s -- --yes --purge
需要帮助？
查看完整文档或在 GitHub 提交 issue。