lxy/workpod
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v1.1.0: Alpine 轻量级 Docker 开发环境 + 敏感凭证清理

Browse Source
This commit is contained in:
lxy
2026-07-27 13:59:18 +08:00
parent feb76081a0
commit ccca0fa62b
51 changed files with 6125 additions and 993 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/03-运维/部署维护手册.md
+428
View File
@@ -0,0 +1,428 @@
# 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"
```