geo/deploy/k3s/README.md

# geo-rankly k3s deployment

这套清单用于把当前 Docker Compose 拓扑搬到单节点或小集群 k3s 中。默认包含：

- infra: `postgres`, `monitoring-postgres`, `pgbouncer`, `monitoring-pgbouncer`, `rabbitmq`, `redis`, `qdrant`, `minio`
- jobs: `migrate`, `minio-init`
- apps: `tenant-api`, `worker-generate`, `kol-assist-worker`, `scheduler`, `ops-api`, `frontend`, `ops-web`
- ingress: `geo-rankly.local` -> `frontend`, `ops.geo-rankly.local` -> `ops-web`

## 1. 准备镜像

在线环境建议推到镜像仓库后修改 `kustomization.yaml` 里的 `images`：

```bash
kubectl kustomize deploy/k3s
```

离线或内网 k3s 可以先用现有打包脚本生成镜像包，再导入到 k3s containerd：

```bash
bash deploy/scripts/package.sh latest linux/amd64
tar xzf geo-rankly-deploy-*-amd64.tar.gz
cd geo-rankly-deploy-*-amd64
sudo k3s ctr images import images.tar
```

如果你的服务器是 ARM，把第二个参数换成 `linux/arm64`。

## 2. 修改密钥

上线前先改 `deploy/k3s/secrets.yaml`：

- `JWT_SECRET`
- `OPS_JWT_SECRET`
- `OPS_DEFAULT_ADMIN_PASSWORD`
- `SCHEDULER_INTERNAL_METRICS_TOKEN`
- `POSTGRES_PASSWORD` / `RABBITMQ_DEFAULT_PASS` / `MINIO_ROOT_*`
- `config/config.yaml` 里的 LLM / SiliconFlow API key
- `config.local.yaml` 里对应的数据库、RabbitMQ、MinIO、JWT 配置

注意：应用运行时通过 `pgbouncer` / `monitoring-pgbouncer` 访问数据库；`migrate` 任务仍然直连 `postgres` / `monitoring-postgres`。数据库密码统一来自 `POSTGRES_PASSWORD` secret，应用配置和 PgBouncer 都会跟随这个 secret。

## 3. 部署

```bash
kubectl apply -k deploy/k3s
kubectl -n geo-rankly get pods -w
```

查看一次性任务：

```bash
kubectl -n geo-rankly logs job/migrate
kubectl -n geo-rankly logs job/minio-init
```

如果是升级后需要重新跑迁移：

```bash
kubectl -n geo-rankly delete job migrate --ignore-not-found
kubectl apply -k deploy/k3s
```

### 3.1 可选安装 Kite dashboard

Kite dashboard 用于管理 k3s/Kubernetes 资源，默认安装到 `kube-system`，并通过 NodePort 暴露：

```bash
kubectl apply -f deploy/k3s/addons/kite.yaml
```

访问：

- Kite dashboard: `http://<node-ip>:30082`
- NAS 示例：`http://192.168.100.19:30082`

注意：Kite 官方清单绑定了 `cluster-admin` 权限，只建议在可信内网使用，不要直接暴露到公网。

## 4. 访问

k3s 默认同时支持两种访问方式。

### 4.1 直接用节点 IP + 端口

`frontend` 和 `ops-web` 已固定为 NodePort：

- tenant admin: `http://<node-ip>:30080`
- ops admin: `http://<node-ip>:30081`

例如 NAS IP 是 `192.168.100.19`：

- tenant admin: `http://192.168.100.19:30080`
- ops admin: `http://192.168.100.19:30081`

### 4.2 用域名 Ingress

k3s 默认 Traefik 会接管 Ingress。先把域名指到 k3s 节点 IP：

```text
<node-ip> geo-rankly.local
<node-ip> ops.geo-rankly.local
```

然后访问：

- tenant admin: `http://geo-rankly.local`
- ops admin: `http://ops.geo-rankly.local`

临时调试时也可用端口转发：

```bash
kubectl -n geo-rankly port-forward svc/frontend 8088:80
kubectl -n geo-rankly port-forward svc/ops-web 8089:80
kubectl -n geo-rankly port-forward svc/rabbitmq 15672:15672
kubectl -n geo-rankly port-forward svc/minio 9001:9001
```

## 5. 常用排查

```bash
kubectl -n geo-rankly get all
kubectl -n geo-rankly describe pod <pod-name>
kubectl -n geo-rankly logs deploy/tenant-api -f
kubectl -n geo-rankly logs deploy/scheduler -f
kubectl -n geo-rankly logs deploy/worker-generate -f
kubectl -n geo-rankly logs deploy/ops-api -f
```

如果应用 Pod 先于 `migrate` 启动失败，通常会自动重启；等 `migrate` 完成后再看 `kubectl -n geo-rankly get pods` 即可。