# WorkPod 部署维护手册

> 版本：1.0 | 更新日期：2026-04-07

---

## 1. 系统概览

WorkPod 是基于 Docker 的轻量级开发环境容器系统，提供 Web 终端 (ttyd) 和 SSH 双入口，支持多实例部署。

### 1.1 架构总览

```
┌─────────────────────────────────────────────────────┐
│                    宿主机 (Windows)                   │
│                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐  │
│  │ workpod-alpine│  │  ws-flux-dev │  │  基础设施   │  │
│  │  :2222 / :7681│  │  :2201 / :7701│  │ mysql/redis│  │
│  └──────────────┘  └──────────────┘  └───────────┘  │
│         ↑                  ↑                          │
│  Alpine 3.23 + Node24    + JDK17/Maven               │
│  ~438MB                  ~438MB                       │
└─────────────────────────────────────────────────────┘
```

### 1.2 实例清单

| 实例 | 类型 | SSH | Web | 镜像 | 内存限制 |
|------|------|-----|-----|------|---------|
| workpod-alpine | 基础实例 | :2222 | :7681 | workpod-alpine:latest (438MB) | 4G |
| ws-flux-dev | Flux 项目 | :2201 | :7701 | ws-flux-dev:latest (438MB) | 4G |
| workpod-test | 测试实例 | :2223 | :7682 | ae5a15cc0c94 (旧镜像) | 4G |

---

## 2. 快速操作

### 2.1 日常启停

```bash
# 启动全部实例
cd E:/wk-lab/workpod/instances/base && docker compose up -d
cd E:/wk-lab/workpod/instances/flux && docker compose up -d

# 停止单个实例
docker compose -f instances/base/docker-compose.yml down
docker compose -f instances/flux/docker-compose.yml down

# 重启（推荐：先 down 再 up）
docker compose -f instances/base/docker-compose.yml down && docker compose -f instances/base/docker-compose.yml up -d
```

### 2.2 连接方式

```bash
# ====== 基础实例 ======
Web 终端:  http://localhost:7681        # 用户 jc / 密码 1234567
SSH:      ssh root@localhost -p 2222     # 密码 workpod123
进入容器:  MSYS_NO_PATHCONV=1 docker exec -it workpod-alpine bash

# ====== Flux 实例 ======
Web 终端:  http://localhost:7701        # 用户 jc / 密码 1234567
SSH:      ssh root@localhost -p 2201     # 密码 workpod123
进入容器:  MSYS_NO_PATHCONV=1 docker exec -it ws-flux-dev bash
```

### 2.3 一键检查状态

```bash
# 容器状态
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# 资源占用
docker stats --no-stream --format "table {{.Name}}\t{{CPUPerc}}\t{{MemUsage}}\t{{NetIO}}"

# 镜像列表
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"
```

---

## 3. 构建与更新

### 3.1 镜像构建

```bash
# 基础镜像（Alpine 3.23 + Node 24 + Claude Code）
cd E:/wk-lab/workpod
docker build -t workpod-alpine:latest .

# Flux 扩展镜像（基础镜像 + LABEL，JDK 通过 volume 挂载）
docker build -t ws-flux-dev:latest -f Dockerfile.flux .
```

**构建产物** (~438MB):
- alpine:3.23 基础 (~7MB)
- 运行时工具 curl/git/ssh/ttyd/tmux/bash (~80MB)
- Node.js v24.14.1 (musl) + claude-code + coding-helper (~200MB)
- entrypoint.sh + ttyd-session.sh (<10KB)

### 3.2 更新 Claude Code / coding-helper

```bash
# 重新构建即可获取最新版（@latest 标签）
docker build --no-cache -t workpod-alpine:latest .
docker build --no-cache -t ws-flux-dev:latest -f Dockerfile.flux .

# 重启容器生效
docker compose -f instances/base/docker-compose.yml down && docker compose -f instances/base/docker-compose.yml up -d
docker compose -f instances/flux/docker-compose.yml down && docker compose -f instances/flux/docker-compose.yml up -d
```

### 3.3 滚动更新（不中断服务）

```bash
# 1. 构建新镜像
docker build -t workpod-alpine:latest .

# 2. 创建新容器（旧容器仍在运行）
docker compose -f instances/base/docker-compose.yml up -d --no-deps --build workpod-alpine

# 3. 确认健康后删除旧容器（自动完成，compose 管理）
```

---

## 4. 运维操作

### 4.1 日志查看

```bash
# 实时日志
docker logs -f workpod-alpine
docker logs -f ws-flux-dev

# 最近 50 行
docker logs --tail 50 workpod-alpine

# 按时间过滤
docker logs --since 2026-04-07T08:00:00 workpod-alpine
```

**日志策略**: json-file 驱动，单文件最大 10MB，保留 3 个文件（每实例最多 30MB）

### 4.2 进入容器调试

```bash
# 交互式 shell（推荐 login shell 以加载 PATH）
MSYS_NO_PATHCONV=1 docker exec -it workpod-alpine bash -lc 'echo $PATH; java -version; node -v'

# 执行单条命令
MSYS_NO_PATHCONV=1 docker exec workpod-alpine bash -lc 'claude --version'
```

> **注意**: Windows Git Bash 下必须加 `MSYS_NO_PATHCONV=1`，否则路径转换会导致错误。

### 4.3 文件传输

```bash
# 宿主机 → 容器
docker cp ./local-file.txt workpod-alpine:/workspace/

# 容器 → 宿主机
docker cp workpod-alpine:/workspace/output.txt ./
```

### 4.4 tmux 会话管理

容器内 ttyd 使用 tmux 管理终端会话：

```bash
# 在 Web 终端或 SSH 中操作
tmux ls                    # 列出所有会话
tmux attach -t session_name  # 加入会话
tmux new -s my_session       # 新建会话

# URL 快速访问指定会话
http://localhost:7681/?session=my_session
```

### 4.5 数据持久化

| 实例 | 宿主机路径 | 容器路径 | 用途 |
|------|-----------|---------|------|
| base | `data/workspace` | `/workspace` | 工作目录 |
| flux | `E:/wk-flux` | `/workspace` | Flux 项目源码 |
| flux | `data/home/flux-dev` | `/root` | 用户配置 (.gitconfig 等) |

---

## 5. 故障排查

### 5.1 容器无法启动

```bash
# 查看启动日志
docker logs workpod-alpine

# 常见问题：
# exit 127 → 命令未找到（镜像损坏或 entrypoint 缺失）
# exit 1   → 健康检查失败（sshd 或 ttyd 未启动）
# exit 255 → 信号处理异常
```

**workpod-test 退出码 127 排查**:
该实例使用旧镜像 ID `ae5a15cc0c94`，可能缺少 entrypoint。修复方法：
```bash
# 方案 A：改用最新基础镜像
# 编辑 instances/test/docker-compose.yml，将 image 改为 workpod-alpine:latest

# 方案 B：重新构建并替换
cd E:/wk-lab/workpod
docker build -t workpod-test:latest .
# 然后修改 test/docker-compose.yml 的 image 字段
```

### 5.2 端口冲突

```bash
# 查看端口占用
netstat -ano | grep :7681

# 端口分配表（避免冲突）
# 2222 / 7681 — workpod-alpine (基础)
# 2201 / 7701 — ws-flux-dev (Flux)
# 2223 / 7682 — workpod-test (测试)
# 新实例建议用 22xx / 77xx / 78xx
```

### 5.3 健康检查失败

```bash
# 手动检查端口
MSYS_NO_PATHCONV=1 docker exec workpod-alpine netstat -tlnp

# 应看到：
# tcp  0  0  0.0.0.0:22    0.0.0.0:*   LISTEN  sshd
# tcp  0  0  0.0.0.0:7681  0.0.0.0:*   LISTEN  ttyd

# 如果 sshd/ttyd 未运行，查看进程
MSYS_NO_PATHCONV=1 docker exec workpod-alpine ps aux
```

### 5.4 内存不足

```bash
# 查看内存使用
docker stats --no-stream

# 当前限制：每个实例 4GB 上限 / 1GB 预留
# 如需调整，编辑对应 docker-compose.yml 的 deploy.resources.limits.memory
```

### 5.5 PATH 环境变量丢失

entrypoint.sh 启动时会自动检测工具链并写入 `/etc/profile.d/dev-tools.sh`。如果 docker exec 中找不到命令：

```bash
# 使用 login shell (-lc) 加载完整环境
MSYS_NO_PATHCONV=1 docker exec -it workpod-alpine bash -lc 'java -version'

# 或手动 source
MSYS_NO_PATHCONV=1 docker exec -it workpod-alpine bash -c 'source /etc/profile && java -version'
```

---

## 6. 清理维护

### 6.1 日常清理命令

```bash
# 清理悬空镜像（已停止容器的孤立层）
docker image prune -f

# 清理未使用的镜像（除运行中容器外的所有未标记镜像）
docker image prune -a -f          # ⚠️ 会删除未运行的镜像

# 清理停止的容器
docker container prune -f

# 清理未使用的网络
docker network prune -f

# 全面清理（悬停资源 + 停止容器 + 未使用网络 + 构建缓存）
docker system prune -f

# 深度清理（包含未使用的镜像）⚠️ 慎用
docker system prune -a -f
```

### 6.2 日志清理

```bash
# 手动清空某容器日志（不重启）
truncate -s 0 $(docker inspect --format='{{.LogPath}}' workpod-alpine)

# 或设置全局日志限制（需编辑 daemon.json）
# /etc/docker/daemon.json:
# { "log-driver": "json-file", "log-opts": { "max-size": "10m", "max-file": "3" } }
```

### 6.3 废弃资源清理记录

| 时间 | 操作 | 释放空间 |
|------|------|---------|
| 2026-04-07 | `docker image prune -f` | 802.8MB (28个悬空层) |

**待清理**:
- `workpod:latest` (2.6GB) — 旧 Ubuntu 版基础镜像
- `dev-box:latest` (2.79GB) — 旧开发箱镜像
- `workpod-alpine:size-test` (436MB) — 大小测试镜像

```bash
# 清理上述废弃镜像（确认无容器引用后）
docker rmi workpod:latest dev-box:latest workpod-alpine:size-test
# 预计释放 ~5.8GB
```

---

## 7. 远程服务器部署

### 7.1 服务器信息

| 项目 | 值 |
|------|-----|
| 服务器 IP | 39.99.243.191 |
| SSH 别名 | flux_dev |
| 部署路径 | /opt/workpod/ |

### 7.2 远程实例

| 实例 | SSH 端口 | Web 端口 | 域名 |
|------|---------|---------|------|
| workpod-1 | 2221 | 7681 | wk.1216.top |
| workpod-alpine | 2222 | 7683 | wk2.1216.top |
| workpod-ada | 2224 | 7685 | ada.1216.top |
| workpod-yxl | 2226 | 7686 | yxl.1216.top |

### 7.3 远程运维命令

```bash
# 通过 ssh-proxy 操作远程服务器
ssh-proxy exec -n flux_dev -c "docker ps --format 'table {{.Names}}\t{{.Status}}'"
ssh-proxy exec -n flux_dev -c "docker logs --tail 30 workpod-1"
ssh-proxy exec -n flux_dev -c "docker system prune -f"
```

---

## 8. 安全备忘

| 项目 | 当前配置 | 风险等级 | 建议 |
|------|---------|---------|------|
| privileged 模式 | 仅基础实例开启 | 高 | 确认是否必需，否则移除 |
| root 用户运行 | 全部实例 | 中 | 开发环境可接受 |
| SSH 密码登录 | PermitRootLogin yes | 内网可接受 | 生产环境禁用 |
| ttyd 认证 | Basic Auth (jc:1234567) | 低-内网 | 可配置强密码 |
| API Key 传递 | docker-compose env | 低 | 不写入文件系统 |
| JDK/Maven 挂载 | ro 只读 | 低 | 安全做法 |

---

## 9. 目录结构速查

```
E:/wk-lab/workpod/
├── Dockerfile                  # 基础镜像构建 (多阶段)
├── Dockerfile.flux              # Flux 扩展镜像
├── entrypoint.sh               # 容器入口脚本
├── ttyd-session.sh             # tmux 会话管理
├── auth-proxy.js               # 认证代理 (可选)
├── wk.1216.conf               # Nginx 反向代理配置
├── SPECS.md                   # 技术规格文档
├── instances/                  # ★ 实例中心
│   ├── .template/             #   实例模板
│   ├── registry.yaml          #   实例注册表
│   ├── base/docker-compose.yml    #   基础实例
│   ├── flux/docker-compose.yml    #   Flux 实例
│   └── test/docker-compose.yml    #   测试实例
├── docs/                      # 文档
│   ├── 00-规范/
│   ├── 01-架构/
│   ├── 02-技术文档/
│   ├── 03-运维/               # ← 本文档
│   └── 04-审核/
├── config/                    # 配置模板
├── static/                    # auth-proxy 静态页
├── data/                      # 运行时数据
│   ├── workspace/             #   基础实例工作区
│   └── home/                  #   用户 home 目录
└── _archive/                  # 历史版本归档
```

---

## 附录：常用命令速查卡

```bash
# ════════════ 构建 ════════════
docker build -t workpod-alpine:latest .
docker build -t ws-flux-dev:latest -f Dockerfile.flux .

# ════════════ 启停 ════════════
docker compose -f instances/base/docker-compose.yml up -d
docker compose -f instances/flux/docker-compose.yml up -d
docker compose -f instances/base/docker-compose.yml down

# ════════════ 查看 ════════════
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
docker stats --no-stream
docker logs -f workpod-alpine

# ════════════ 进入 ════════════
MSYS_NO_PATHCONV=1 docker exec -it workpod-alpine bash
ssh root@localhost -p 2222           # workpod123
# http://localhost:7681              # jc / 1234567

# ════════════ 清理 ════════════
docker image prune -f                # 悬空镜像
docker system prune -f               # 全面清理
docker rmi <image>                   # 删除指定镜像

# ════════════ 远程 ════════════
ssh-proxy exec -n flux_dev -c "docker ps"
```