返回

安装 Kageos

本地试用、Linux 直连部署、已有反向代理接入都可以走同一个安装器。首次安装会输出 system 登录信息。

前置条件

  • macOS 或 Windows：安装 Podman Desktop，并完成 Podman machine 初始化
  • Linux 生产服务器：需要 sudo 权限、公网 IP 或域名，以及足够存放镜像和数据的磁盘
  • 桌面 Podman machine 建议 6 GB 内存、20 GB 磁盘；Linux 生产建议至少 4 GB，推荐 8 GB
  • 桌面本地默认使用 8080 端口；生产部署可以直接占用 80/443，也可以放在 Caddy 或 Nginx 后面

选择平台

macOS 和 Windows 是本地试用；Linux 是生产环境部署。

本地试用

在 macOS 上本地运行 Kageos

适合在自己的 Mac 上先试用 Kageos，还不需要准备 Linux 服务器。

查看 install.sh 下载 Podman Desktop

安装并运行

安装 Podman Desktop，完成 Podman machine 初始化后运行 Kageos。

$ brew install --cask podman-desktop
$ curl -fsSL https://kageos.ai/install.sh | bash -s -- --port 8080
这条路径会做什么
  • 运行 Kageos 安装器前，先打开 Podman Desktop 并完成 Podman machine 初始化。
  • 创建持久化的 kageos-data 数据卷，并运行 qiayanai/kageos 镜像。
  • 首次安装成功后，安装器会输出 system 登录信息。
安装完成后
访问地址
http://localhost:8080
安装完成后，在这台 Mac 上打开这个地址。
用户名
system
首次启动时创建的内置管理员账号。
密码
kageos password
安装器会输出密码；这个命令可以再次查看。

先选生产部署形态

运行安装器前，先判断这台服务器的入口是谁。传给 --base-url 的地址，始终应该是用户最终在浏览器里打开的公网地址。

干净服务器

Kageos 直接占用 80/443

如果宿主机没有其他 Web 服务监听公网端口，使用默认命令即可。Kageos 容器内会处理 HTTP、HTTPS 和跳转。

已有入口

Caddy 或 Nginx 负责 TLS

如果 80/443 已经被反向代理占用，安装时使用 --tls-mode external，让代理把流量转到 Kageos 的本机 HTTP 端口。

首次验证

IP + HTTP 快速试跑

服务器 IP 地址适合先确认镜像、端口和容器链路。邀请真实用户前，应切到域名和 HTTPS。

反向代理部署

当宿主机已经运行 Caddy、Nginx、云负载均衡或平台 Ingress 时，推荐让入口继续占用 80/443，Kageos 只在本机 HTTP 端口提供服务。

把 Kageos 装在代理后面

用户访问的仍然是 HTTPS 域名。external 表示 TLS 在进入 Kageos 前已经由外层代理终止。

$ curl -fsSL https://kageos.ai/install-prod.sh | sudo bash -s -- \
--base-url https://app.example.com \
--tls-mode external \
--http-port 10001

Caddy 示例

域名 A 记录指向服务器、公网 TCP 80/443 放行后，Caddy 会自动申请和续期证书。

app.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:10001
}

Nginx 示例

如果团队已有 Nginx 证书和发布流程，可以只把业务流量转发给 Kageos。

location / {
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://127.0.0.1:10001;
}

端口策略

反代模式下，公网只需要开放 80/443 给入口代理。不要把 Kageos 上游端口加入公网安全组，除非你明确需要直连访问。

# 公网入口
80/tcp, 443/tcp -> Caddy 或 Nginx
# 本机上游
127.0.0.1:10001 -> Kageos

访问不通排查清单

把问题拆成服务器、代理、DNS 和客户端缓存四段。服务器上 HTTPS 探测成功，通常说明 Kageos 和反向代理都已经正常。

在服务器上执行

$ curl -4 ifconfig.me; echo
$ dig +short app.example.com A @1.1.1.1
$ sudo ss -lntp | grep -E ':(80|443|10001)\s'
$ curl -I http://127.0.0.1:10001
$ curl -I https://app.example.com
$ sudo journalctl -u caddy -n 100 --no-pager -l

在访问端执行

$ dig +short app.example.com
$ curl -Iv https://app.example.com
# macOS DNS 缓存
$ sudo dscacheutil -flushcache
$ sudo killall -HUP mDNSResponder
# Chrome 缓存
chrome://net-internals/#dns
chrome://net-internals/#sockets

部署了什么

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.ai/uninstall-prod.sh | sudo bash -s -- --yes --purge

需要帮助？

查看完整文档或在 GitHub 提交 issue。

GitHub 仓库 提交 Issue