lxy/workpod
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
workpod/docs/03-运维/部署维护手册.md
T

13 KiB
Raw Permalink Blame History

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 日常启停

# 启动全部实例
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 连接方式

# ====== 基础实例 ======
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 一键检查状态

# 容器状态
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 镜像构建

# 基础镜像（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

# 重新构建即可获取最新版（@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 滚动更新（不中断服务）

# 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 日志查看

# 实时日志
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 进入容器调试

# 交互式 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 文件传输

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

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

4.4 tmux 会话管理

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

# 在 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 容器无法启动

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

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

workpod-test 退出码 127 排查: 该实例使用旧镜像 ID ae5a15cc0c94，可能缺少 entrypoint。修复方法：

# 方案 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 端口冲突

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

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

5.3 健康检查失败

# 手动检查端口
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 内存不足

# 查看内存使用
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 中找不到命令：

# 使用 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 日常清理命令

# 清理悬空镜像（已停止容器的孤立层）
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 日志清理

# 手动清空某容器日志（不重启）
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) — 大小测试镜像
# 清理上述废弃镜像（确认无容器引用后）
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 远程运维命令

# 通过 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/                  # 历史版本归档

附录：常用命令速查卡

# ════════════ 构建 ════════════
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"
Reference in New Issue View Git Blame Copy Permalink