429 lines
13 KiB
Markdown
429 lines
13 KiB
Markdown
# 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"
|
||
```
|