# tongmodel_deploy

**Repository Path**: tongmodel/tongmodel_deploy

## Basic Information

- **Project Name**: tongmodel_deploy
- **Description**: 一键部署
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-24
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TongModel ARM64 离线部署说明

本文档描述 `/root/tongmodel_deploy` 的离线部署流程。当前部署面向 ARM64 环境，默认使用 Docker 启动本地 `local-k3s`，再把 Cube Studio、Headlamp、Label Studio、IAM、Keycloak 等组件部署起来。

## 目录约定

部署脚本需要两个参数：

```bash
bash install.sh <镜像目录> <数据目录>
```

示例：

```bash
cd /root/tongmodel_deploy
bash install.sh /home/tongmodel /home/tongmodel
```

参数说明：

- `<镜像目录>`：离线镜像包所在目录，要求下面包含 `*-images` 目录，例如 `/home/tongmodel/rancher-images`、`/home/tongmodel/bussiness-images`、`/home/tongmodel/kubeflow-images`、`/home/tongmodel/workflow-images`。其中 `rancher-images` 目录只用于存放 `rancher/k3s` 及其运行时镜像，不部署 Rancher 管理平台。
- `<数据目录>`：运行数据目录。脚本会在该目录下创建 `local-k3s`、`k8s`、`labelstudio` 等数据目录。

常用目录：

```text
/home/tongmodel/rancher-images
/home/tongmodel/bussiness-images
/home/tongmodel/kubeflow-images
/home/tongmodel/workflow-images
/home/tongmodel/local-k3s
/home/tongmodel/k8s
```

## 默认组件

默认安装：

- `local-k3s`
- `cube_studio`
- `Headlamp`
- `Label Studio`
- `IAM`
- `Keycloak`

## 部署前检查

如果目标机器还没有 Docker、Docker Compose、kubectl，可先在一台已安装好基础环境且可联网的 ARM64 机器上导出基础环境包：

```bash
cd /root/tongmodel_deploy
PULL_MISSING_IMAGES=yes OUTPUT_TAR=/home/tongmodel/base-env-aarch64.tar.gz bash export-base-env.sh
```

把 `base-env-aarch64.tar.gz` 拷贝到离线机器后安装：

```bash
sudo DOCKER_DATA_ROOT=/home/docker bash install-base-env-from-tar.sh /path/to/base-env-aarch64.tar.gz
```

说明：

- 基础环境包包含 Docker、Docker Compose、kubectl、`docker.service` 和 K3s 运行时镜像。
- `PULL_MISSING_IMAGES=yes` 会补拉 `rancher/k3s`、pause、coredns、local-path-provisioner、metrics-server 等 K3s 运行时镜像。
- 安装脚本默认不覆盖已有 `/etc/docker/daemon.json`；如需强制写入 Docker 数据目录，使用 `FORCE_DOCKER_DAEMON_JSON=yes`。
- 如果已经手工解压，也可以直接进入解压目录执行 `sudo bash install-base-env.sh`。

确认 Docker 可用：

```bash
docker ps
```

确认镜像目录存在：

```bash
find /home/tongmodel -maxdepth 2 -type d -name '*-images' | sort
```

确认离线镜像包存在：

```bash
find /home/tongmodel -mindepth 2 -maxdepth 2 -type f -path '/home/tongmodel/*-images/*' \( -name '*.tar' -o -name '*.tar.gz' \) | sort
```

当前 `start-local-k3s.sh` 会自动扫描 `<镜像目录>/*-images/*.tar` 和 `<镜像目录>/*-images/*.tar.gz`，并只导入 `arm64/aarch64` 镜像到 K3s containerd。非 ARM64 镜像会跳过。

## 一键部署

默认部署：

```bash
cd /root/tongmodel_deploy
bash install.sh /home/tongmodel /home/tongmodel
```

指定宿主机 IP：

```bash
cd /root/tongmodel_deploy
MACHINE_IP=10.17.55.61 bash install.sh /home/tongmodel /home/tongmodel
```

## install.sh 执行流程

主要步骤：

1. 检查固定端口占用。
2. 检查 Docker 环境。
3. 清理未使用的 Docker 镜像和容器缓存。
4. 通过 `load_images.sh` 把最小离线镜像集合加载到宿主 Docker。
5. 根据宿主机 IP 和数据目录替换部署配置。
6. 准备 Label Studio 数据目录和权限。
7. 启动 IAM。
8. 启动 Keycloak。
9. 启动 Label Studio。
10. 启动本地 `local-k3s`。
11. 部署 Cube Studio 到 K8s。
12. 部署 Headlamp。

注意：

- `load_images.sh` 使用 `docker load -i`，加载到宿主 Docker。
- `start-local-k3s.sh` 使用 `ctr -n k8s.io images import`，导入到 `local-k3s` 内部 containerd，供 Pod 使用。
- 只加载到宿主 Docker 的镜像，K3s Pod 不一定能直接使用；需要进入 K3s containerd。

## 本地 K3s 镜像导入规则

`start-local-k3s.sh` 不再写死镜像文件列表，而是自动扫描：

```text
<镜像目录>/*-images/*.tar
<镜像目录>/*-images/*.tar.gz
```

导入规则：

- 只导入 `architecture=arm64` 或 `architecture=aarch64` 的镜像归档。
- 非 ARM64 镜像会打印跳过日志。
- 镜像导入目标是 `local-k3s` 的 containerd namespace：`k8s.io`。

手动导入单个镜像到 K3s 的命令示例：

```bash
cat /home/tongmodel/workflow-images/model-onnx-yolo-serving_20240601.tar \
  | docker exec -i local-k3s ctr -n k8s.io images import -
```

查看 K3s 内镜像：

```bash
docker exec local-k3s ctr -n k8s.io images ls
```

## 固定访问地址

部署完成后访问：

```text
cube_studio:  http://<MACHINE_IP>:30080/frontend/
Headlamp:     http://<MACHINE_IP>:30082/
Label Studio: http://<MACHINE_IP>:8088/
cube MySQL:   <MACHINE_IP>:31306
```

常用固定端口：

- `6443`：local-k3s API
- `30080`：cube_studio
- `30082`：Headlamp
- `31306`：cube_studio MySQL
- `8088`：Label Studio
- `30900`：Label MinIO API
- `30901`：Label MinIO Console
- `10087`：IAM UI
- `10083`：Keycloak
- `9090`：Prometheus
- `3000`：Grafana

## 推理服务端口

Cube Studio 推理服务会生成类似：

```text
http://<MACHINE_IP>:20200/
```

当前 `local-k3s` 是 Docker 容器内的 K3s，推理服务外部 Service 通常是 `ClusterIP + externalIPs`，宿主机不会自动监听 `20200` 这类动态推理端口。因此需要手动开启端口转发。

开启推理服务端口：

```bash
/root/tongmodel_deploy/open-k8s-service-port.sh 20200 service yolov8-202601121-external 20200
```

脚本参数：

```bash
/root/tongmodel_deploy/open-k8s-service-port.sh <端口> [namespace] [service] [target_port]
```

验证：

```bash
ss -ltnp | grep ':20200'
curl http://10.17.55.61:20200/
docker ps | grep k8s-port-forward-service-20200
```

停止转发：

```bash
docker rm -f k8s-port-forward-service-20200
```

更多说明见：

```text
docs/k8s-service-port-forward.md
```

## Headlamp 登录

访问：

```text
http://<MACHINE_IP>:30082/
```

获取登录 Token：

```bash
bash /root/tongmodel_deploy/get-headlamp-token.sh
```

生成短时 Token：

```bash
TOKEN_DURATION=24h bash /root/tongmodel_deploy/get-headlamp-token.sh
```

## 状态检查

查看 Docker 容器：

```bash
docker ps
```

查看 K3s 节点：

```bash
docker exec local-k3s kubectl get nodes -o wide
```

查看核心命名空间 Pod：

```bash
docker exec local-k3s kubectl get pod -A
```

查看 Cube Studio：

```bash
docker exec local-k3s kubectl get pod,svc -n infra
```

查看推理服务：

```bash
docker exec local-k3s kubectl get pod,svc,endpoints -n service
```

查看 K3s 内镜像：

```bash
docker exec local-k3s ctr -n k8s.io images ls
```

## 端口冲突处理

安装脚本会在启动前检查固定端口。如果端口被占用，会输出：

- 当前占用详情
- 建议可用端口范围
- 可覆盖的环境变量名

常用可覆盖变量：

```bash
CUBE_STUDIO_NODEPORT=30080
HEADLAMP_NODEPORT=30082
CUBE_STUDIO_MYSQL_NODEPORT=31306
LABEL_STUDIO_PORT=8088
K3S_API_PORT=6443
```

示例：

```bash
CUBE_STUDIO_NODEPORT=30081 HEADLAMP_NODEPORT=30083 bash install.sh /home/tongmodel /home/tongmodel
```

## 卸载

卸载全部默认组件：

```bash
cd /root/tongmodel_deploy
bash uninstall.sh /home/tongmodel /home/tongmodel
```

## 联网环境制作镜像包

联网机器上制作离线镜像：

```bash
cd /root/tongmodel_deploy
bash build-images.sh
```

只制作业务镜像：

```bash
bash build-images.sh business
```

只制作 `local-k3s` 运行时镜像：

```bash
bash build-images.sh k3s
```

## 常见问题

### Pod 提示镜像不存在

先确认镜像是否在 K3s containerd 中：

```bash
docker exec local-k3s ctr -n k8s.io images ls | grep '<镜像名>'
```

如果没有，手动导入：

```bash
cat <镜像tar包> | docker exec -i local-k3s ctr -n k8s.io images import -
```

### Pod 报 exec format error

通常是镜像架构不匹配。当前环境是 ARM64，镜像必须是 `linux/arm64`。

查看 K3s 节点架构：

```bash
docker exec local-k3s uname -m
```

查看 K3s 内镜像架构：

```bash
docker exec local-k3s ctr -n k8s.io images ls | grep '<镜像名>'
```

### PVC 不存在或挂载失败

检查 `service` 命名空间 PVC：

```bash
docker exec local-k3s kubectl get pvc -n service
```

检查 PV：

```bash
docker exec local-k3s kubectl get pv
```

当前数据目录由 `install.sh` 第二个参数决定，K8s hostPath 会使用：

```text
<数据目录>/k8s
```

### 推理地址本机通，局域网不通

检查端口监听：

```bash
ss -ltnp | grep ':20200'
```

检查 firewalld：

```bash
firewall-cmd --list-ports
```

手动开启：

```bash
/root/tongmodel_deploy/open-k8s-service-port.sh 20200 service yolov8-202601121-external 20200
```