RCoder 离线部署指南
本文档面向政企/内网客户：目标机器无公网访问，所有镜像与依赖必须随部署包交付。
目录内容（解压 rcoder-offline-*.tar.gz 后）
.
├── install.sh # 主安装脚本
├── rewrite-registry.sh # registry 模式: re-tag + push 辅助脚本
├── README.md # 本文件
├── values-dev.yaml # RCoder dev 环境 values
├── values-prod.yaml # RCoder prod 环境 values
├── values-offline.yaml # 离线 registry 覆盖模板
├── images/
│ ├── all-images.tar # 所有镜像的 docker save 产物
│ └── images.txt # 镜像清单
├── charts/
│ └── rcoder-*.tgz # RCoder Helm chart
├── longhorn/
│ └── longhorn-v*.yaml # Longhorn 全量 manifest
├── juicefs-csi/
│ └── juicefs-csi-v*.yaml # JuiceFS CSI Driver 官方 manifest
└── manifests/ # 原始 Kustomize 资产 (参考, 不必使用)
前置条件
在离线机器上，提前准备好：
| 组件 | 版本 | 说明 |
|---|---|---|
| K8s | 1.19+ | 已部署, kubeconfig 已配置 |
| kubectl | 与集群匹配 | kubectl cluster-info 能通 |
| helm | 3.x | 用于 helm upgrade --install |
| docker | 最新 | 仅 registry 模式需要 |
| k3s / nerdctl / ctr | 最新 | 仅 direct 模式需要 |
| open-iscsi | 任意 | Longhorn 依赖 (Ubuntu: apt install open-iscsi) |
两种部署模式
模式 A: direct（推荐单节点 / 小集群）
直接把镜像 import 到节点 containerd，无需私有 registry。适合 k3s 单节点或 3-5 节点小集群。
多节点集群需要在每个节点上依次执行镜像导入。
# 1. 解压 bundle (可通过 make k8s-offline-import 一步完成)
tar xzf rcoder-offline-<version>-<arch>.tar.gz -C /opt/rcoder-offline
cd /opt/rcoder-offline
# 2. 一键安装
sudo ./install.sh --mode=direct --env=dev
# 生产环境
sudo ./install.sh --mode=direct --env=prod \
--set credentials.postgresql.password='<prod-pg-pass>' \
--set credentials.minio.rootPassword='<prod-minio-pass>'
多节点注意: 每个节点都要执行
sudo k3s ctr -n k8s.io image import images/all-images.tar或把 bundle scp 到每个节点各跑一次--skip-juicefs-csi --skip-longhorn只做镜像导入。
模式 B: registry（推荐多节点 / 生产）
把镜像重新打 tag 推送到客户的私有 registry（Harbor / Nexus / 阿里云 ACR 内网实例），K8s 按常规流程拉取。
前置: 集群节点能访问私有 registry，并配置好拉取凭据（如需要）。
# 1. 解压
tar xzf rcoder-offline-<version>-<arch>.tar.gz -C /opt/rcoder-offline
cd /opt/rcoder-offline
# 2. 如果私有 registry 需要认证, 先登录 docker daemon
docker login harbor.internal
# 3. 安装 (一条命令完成推送+部署)
./install.sh \
--mode=registry \
--registry=harbor.internal/rcoder \
--thirdparty-registry=harbor.internal/thirdparty \
--env=prod
推送完成后，镜像会以如下命名出现在 registry：
| 原镜像 | 推送目标 |
|---|---|
nuwax-docker-images-registry.cn-hangzhou.cr.aliyuncs.com/dev/rcoder:latest |
harbor.internal/rcoder/rcoder:latest |
postgres:16-alpine |
harbor.internal/thirdparty/postgres:16-alpine |
longhornio/longhorn-manager:v1.7.2 |
harbor.internal/thirdparty/longhornio/longhorn-manager:v1.7.2 |
registry.k8s.io/sig-storage/csi-provisioner:v5.1.0 |
harbor.internal/thirdparty/sig-storage/csi-provisioner:v5.1.0 |
如果集群需要 imagePullSecret:
kubectl -n nuwax-rcoder-prod create secret docker-registry harbor-pull \
--docker-server=harbor.internal \
--docker-username=<user> \
--docker-password=<pass>
# 重新安装时:
./install.sh ... --set 'global.imagePullSecrets[0].name=harbor-pull'
常见操作
查看部署状态
kubectl get pods -n nuwax-rcoder-dev
kubectl get svc -n nuwax-rcoder-dev
kubectl rollout status deploy/rcoder -n nuwax-rcoder-dev
访问服务
# NodePort
NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
curl http://${NODE_IP}:30080/health # dev
curl http://${NODE_IP}:30081/health # prod
# 或 port-forward
kubectl port-forward -n nuwax-rcoder-dev svc/rcoder 8087:8087
curl http://localhost:8087/health
卸载
helm uninstall rcoder-dev --namespace nuwax-rcoder-dev
# 彻底删除 (包含 PVC)
kubectl delete pvc --all -n nuwax-rcoder-dev
kubectl delete namespace nuwax-rcoder-dev
升级
收到新 bundle 后直接重新跑 install.sh（helm upgrade --install 会自动升级）：
./install.sh --mode=registry --registry=harbor.internal/rcoder --env=prod
跳过选项
| 参数 | 用途 |
|---|---|
--skip-longhorn |
集群已有其他 CSI (Ceph/NFS/CSI-local-path)，不装 Longhorn |
--skip-juicefs-csi |
集群已有 JuiceFS CSI 或用其他 RWX 方案 |
--skip-image-import |
镜像已手工导入，调试用 |
多节点镜像批量导入（direct 模式）
install.sh 只在执行节点导入镜像。多节点集群建议写一个辅助脚本循环每个节点：
NODES=(node1 node2 node3)
for n in "${NODES[@]}"; do
scp images/all-images.tar root@$n:/tmp/
ssh root@$n 'sudo k3s ctr -n k8s.io image import /tmp/all-images.tar && rm /tmp/all-images.tar'
done
# 然后在控制平面节点跑:
./install.sh --mode=direct --env=prod --skip-image-import
故障排查
Pod 长时间 Pending
kubectl describe pod -n nuwax-rcoder-dev <pod-name>
# 常见原因:
# - ImagePullBackOff -> 节点 containerd 没有镜像 (direct 模式漏了某节点)
# - 长时间 ContainerCreating -> Longhorn / JuiceFS CSI 未就绪
JuiceFS 挂载失败
kubectl logs -n kube-system -l app=juicefs-csi-driver-node --tail=50
# 检查 postgresql / minio 是否就绪
kubectl get pods -n nuwax-rcoder-dev -l app=postgresql
kubectl get pods -n nuwax-rcoder-dev -l app=minio
Longhorn 无法启动
# 常见原因: open-iscsi 未安装
ssh <node> "sudo apt install -y open-iscsi && sudo systemctl enable --now iscsid"
kubectl delete pod -n longhorn-system -l app=longhorn-manager --force
版本信息
本 bundle 固定了以下版本：
- RCoder: (由构建时的 git tag 决定, 见
images/images.txt) - PostgreSQL: 16-alpine
- MinIO: 固定 release tag
- JuiceFS Mount: ce-v1.3.1
- JuiceFS CSI: v0.31.3 (官方 deploy/k8s.yaml; helm 仓库已停更)
- Longhorn: v1.7.2
升级任意组件需要重新构建 bundle（make k8s-offline-bundle），本离线包不能在线更新。