578 lines
21 KiB
Markdown
578 lines
21 KiB
Markdown
# WorkPod Alpine 技术规格
|
||
|
||
> 版本：1.1.0 | 更新日期：2026-04-07 | 镜像版本：workpod-alpine:latest (1.1.0)
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
WorkPod Alpine 是一个**轻量级 Docker 开发环境容器**，基于 Alpine Linux 3.23 构建，提供 Web 终端（ttyd）和 SSH 双入口，支持多实例部署、开发工具自动检测、tmux 多会话管理。
|
||
|
||
### 核心特性
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| **镜像大小** | ~436MB（多阶段构建，Ubuntu 版的 1/6） |
|
||
| **基础镜像** | alpine:3.23 (~7MB) |
|
||
| **运行时内存** | 80-120MB 基线 + 应用 |
|
||
| **启动时间** | ~2.5 秒 |
|
||
| **Web 终端** | ttyd + tmux 会话管理 |
|
||
| **AI 工具集成** | Claude Code + coding-helper + 智谱 GLM |
|
||
|
||
### 适用场景
|
||
|
||
- 远程开发环境（浏览器直接访问，无需本地配置）
|
||
- 团队成员统一开发环境
|
||
- 多项目隔离部署（每个项目独立容器实例）
|
||
|
||
---
|
||
|
||
## 2. 架构设计
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "Docker Host"
|
||
DC["docker-compose.yml<br/>基础实例"]
|
||
DCF["docker-compose.flux.yml<br/>Flux 项目"]
|
||
DCA["docker-compose-alpine.yml<br/>备用/测试"]
|
||
end
|
||
|
||
subgraph "Images"
|
||
BASE["workpod-alpine:latest<br/>Alpine 3.23 + Node 24<br/>~436MB"]
|
||
FLUX["ws-flux-dev:latest<br/>BASE + JDK17/Maven 挂载"]
|
||
end
|
||
|
||
subgraph "Containers"
|
||
W1["workpod-alpine<br/>SSH :2222 / Web :7681<br/>network: workpod-alpine-network"]
|
||
W2["ws-flux-dev<br/>SSH :2201 / Web :7701<br/>network: workpod-flux-network"]
|
||
end
|
||
|
||
subgraph "Host Mounts"
|
||
WS["E:/wk-flux → /workspace"]
|
||
JDK["D:/Java/jdk-musl-17 → /opt/jdk-musl-17 :ro"]
|
||
MVN["D:/Java/maven-mvnd → /opt/maven-mvnd :ro"]
|
||
end
|
||
|
||
subgraph "Optional"
|
||
AP["auth-proxy.js<br/>认证代理 :8080<br/>Basic Auth + Token"]
|
||
NX["nginx (wk.1216.top)<br/>SSL 终止 + 反向代理"]
|
||
end
|
||
|
||
DC -->|"build"| BASE
|
||
DCF -->|"build"| FLUX
|
||
DCA -->|"image"| W1
|
||
BASE --> W1
|
||
FLUX --> W2
|
||
W2 --> WS
|
||
W2 --> JDK
|
||
W2 --> MVN
|
||
AP -.->|"proxy"| W1
|
||
AP -.->|"proxy"| W2
|
||
NX -.->|"ssl termination"| AP
|
||
```
|
||
|
||
### 组件职责
|
||
|
||
| 组件 | 职责 | 状态 |
|
||
|------|------|------|
|
||
| `Dockerfile` | 基础镜像构建（Node + Claude Code + coding-helper） | 活跃 |
|
||
| `Dockerfile.flux` | Flux 项目扩展（基于基础镜像，JDK 外挂） | 活跃 |
|
||
| `entrypoint.sh` | 容器入口：信号处理、PATH 检测、服务启停 | 活跃 |
|
||
| `ttyd-session.sh` | tmux 会话管理（URL 参数 / 交互菜单） | 活跃 |
|
||
| `docker-compose.yml` | 基础实例编排 | 活跃 |
|
||
| `docker-compose.flux.yml` | Flux 项目实例编排 | 活跃 |
|
||
| `docker-compose-alpine.yml` | 备用编排（多端口 /root 挂载） | 归档备用 |
|
||
| `auth-proxy.js` | 认证代理（Basic Auth + Token + WS 代理） | 可选组件 |
|
||
| `download-packages.sh` | 离线包下载脚本 | 归档备用 |
|
||
| `entrypoint-test.sh` | Test 入口（developer 用户 + 全权限 Claude） | 已归档 |
|
||
|
||
---
|
||
|
||
## 3. 镜像构建
|
||
|
||
### 3.1 基础镜像 (Dockerfile)
|
||
|
||
```dockerfile
|
||
# 多阶段构建
|
||
FROM alpine:3.23 AS builder # 阶段1: 构建
|
||
# → 安装 xz, libstdc++
|
||
# → 解压 Node.js v24.14.1 (musl)
|
||
# → npm install -g claude-code@latest, coding-helper@latest
|
||
# → npm cache clean
|
||
|
||
FROM alpine:3.23 # 阶段2: 运行时
|
||
# → apk add: curl git openssh-server bash ttyd tmux libstdc++
|
||
# → ssh-keygen + chpasswd + PermitRootLogin yes
|
||
# COPY --from=builder /opt/node /usr/local
|
||
# → npm config set registry npmmirror.com
|
||
# COPY --chmod=755 entrypoint.sh /entrypoint.sh
|
||
# COPY --chmod=755 ttyd-session.sh /opt/ttyd-session.sh
|
||
```
|
||
|
||
**构建产物**：
|
||
|
||
| 层 | 内容 | 大小 |
|
||
|----|------|------|
|
||
| alpine:3.23 | 基础系统 | ~7MB |
|
||
| runtime tools | curl/git/ssh/ttyd/tmux/bash | ~80MB |
|
||
| /usr/local | Node.js + npm 全局包 | ~200MB |
|
||
| scripts | entrypoint + ttyd-session | <10KB |
|
||
| **总计** | | **~436MB (压缩后)** |
|
||
|
||
### 3.2 Flux 扩展镜像 (Dockerfile.flux)
|
||
|
||
```dockerfile
|
||
FROM workpod-alpine:latest
|
||
# 无额外 RUN 指令
|
||
# JDK 通过 docker-compose volume 从宿主机挂载
|
||
# JAVA_HOME 由 environment 设置
|
||
EXPOSE 22 7681
|
||
ENTRYPOINT ["/entrypoint.sh"]
|
||
```
|
||
|
||
Flux 镜像与基础镜像几乎等大（仅增加 LABEL 元数据），JDK/Maven 不占用镜像空间。
|
||
|
||
### 3.3 构建命令
|
||
|
||
```bash
|
||
# 基础镜像
|
||
docker build -t workpod-alpine:latest .
|
||
|
||
# Flux 镜像（依赖基础镜像先构建好）
|
||
docker build -t ws-flux-dev:latest -f Dockerfile.flux .
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 容器编排
|
||
|
||
### 4.1 三份 Compose 文件对比
|
||
|
||
| 配置项 | docker-compose.yml (基础) | docker-compose.flux.yml (Flux) | docker-compose-alpine.yml (备用) |
|
||
|--------|--------------------------|-------------------------------|--------------------------------|
|
||
| **Service 名** | workpod-alpine | ws-flux-dev | workpod-alpine |
|
||
| **Container 名** | workpod-alpine | ws-flux-dev | workpod-alpine |
|
||
| **SSH 端口** | 2222 → 22 | 2201 → 22 | 2223 → 22 |
|
||
| **Web 端口** | 7681 → 7681 | 7701 → 7681 | 7683→7681, 7684→7682 |
|
||
| **工作空间挂载** | ./data/workspace → /workspace | E:/wk-flux → /workspace | data/workpod-alpine/workspace → /workspace |
|
||
| **JDK 挂载** | 无 | D:/Java/jdk-musl-17:ro → /opt/jdk-musl-17 | 无 |
|
||
| **Maven 挂载** | 无 | D:/Java/maven-mvnd:ro → /opt/maven-mvnd | 无 |
|
||
| **智谱 GLM env** | 无 | ANTHROPIC_* 5 项传递 | 无 |
|
||
| **privileged** | true | false | true |
|
||
| **内存限制** | 4G limit / 1G reserve | 4G limit / 1G reserve | 无 |
|
||
| **健康检查** | 有 | 有 | 无 |
|
||
| **日志轮转** | 10m × 3 | 10m × 3 | 无 |
|
||
| **网络** | workpod-alpine-network | workpod-flux-network | workpod-network |
|
||
|
||
### 4.2 启动命令
|
||
|
||
```bash
|
||
# 基础实例
|
||
docker compose up -d
|
||
|
||
# Flux 项目实例
|
||
docker compose -f docker-compose.flux.yml up -d
|
||
|
||
# 备用实例
|
||
docker compose -f docker-compose-alpine.yml up -d
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 运行时
|
||
|
||
### 5.1 启动流程 (entrypoint.sh)
|
||
|
||
```
|
||
trap SIGTERM/SIGINT/SIGQUIT → cleanup()
|
||
│
|
||
▼
|
||
┌─ PATH 自动检测 ─────────────────────────┐
|
||
│ JAVA_HOME → ${JAVA_HOME}/bin │
|
||
│ MAVEN_HOME → ${MAVEN_HOME}/bin │
|
||
│ .cargo/bin → Rust (cargo/rustup) │
|
||
│ gvm/gos → Go (gvm 版本管理) │
|
||
│ .pyenv → Python (pyenv) │
|
||
│ go/bin → Go (自定义安装) │
|
||
│ .local/bin → 本地工具 │
|
||
│ rust-* → Rust 独立安装 │
|
||
└──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─ 写入 /etc/profile.d/dev-tools.sh ─────┐│ (新 shell 会话也生效)
|
||
│ (同样逻辑，确保持久化) │
|
||
└──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─ 启动服务 ────────────────────────────────┐
|
||
│ /usr/sbin/sshd │
|
||
│ ttyd -W -c "${TTYD_CREDENTIALS}" \ │
|
||
│ -t fontSize=16 \ │
|
||
│ -t theme='{"background":"#1a1a2e"}' │
|
||
│ /opt/ttyd-session.sh & │
|
||
└──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─ 健康检查 ────────────────────────────────┐
|
||
│ kill -0 $TTYD_PID → ttyd 存活? │
|
||
│ pidof sshd → sshd 存活? │
|
||
│ 任一失败 → exit 1 │
|
||
└──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─ 显示环境信息 ──────────────────────────┐
|
||
│ Node/npm/Claude/Rust/Go/Python 版本 │
|
||
│ 连接方式 (Web URL + SSH 命令) │
|
||
└──────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
exec sleep infinity (PID 1)
|
||
```
|
||
|
||
### 5.2 信号处理
|
||
|
||
```bash
|
||
cleanup() {
|
||
kill $TTYD_PID # ttyd 后台进程
|
||
kill $SSHD_PID # sshd (注意: 当前 PID 未追踪，实际用 pkill)
|
||
wait # 等待子进程退出
|
||
exit 0
|
||
}
|
||
trap cleanup SIGTERM SIGINT SIGQUIT
|
||
```
|
||
|
||
### 5.3 ttyd 会话管理 (ttyd-session.sh)
|
||
|
||
```
|
||
用户访问 http://host:7681
|
||
│
|
||
▼
|
||
┌─ URL 带 ?session=xxx ? ──────┐
|
||
│ 是 → 解析 session 名称 │
|
||
│ ↓ │
|
||
│ 过滤非法字符 (仅 a-zA-Z0-9_-) │
|
||
│ ↓ │
|
||
│ tmux attach (存在) 或 new (不存在)│
|
||
│ │
|
||
│ 否 → 显示交互式菜单 │
|
||
│ ┌─────────────────────────┐ │
|
||
│ │ [1] session_a │ │
|
||
│ │ [2] session_b │ │
|
||
│ │ 输入编号或新名称 │ │
|
||
│ └─────────────────────────┘ │
|
||
│ ↓ │
|
||
│ 数字 → 映射到已有 session │
|
||
│ 字符串 → 新建 session │
|
||
│ ↓ │
|
||
│ exec tmux attach/new │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
**安全设计**：
|
||
- Session 名过滤：`tr -cd 'a-zA-Z0-9_-'` 防止注入
|
||
- 共享模式：不带 `-d` 参数，多人可同时查看同一 session
|
||
- 默认值：空输入默认为 `default`
|
||
|
||
---
|
||
|
||
## 6. 服务端口与连接方式
|
||
|
||
### 6.1 端口分配表
|
||
|
||
| 实例 | SSH | Web 终端 (ttyd) | 网络 |
|
||
|------|-----|---------------|------|
|
||
| **workpod-alpine** (基础) | 2222 | 7681 | workpod-alpine-network |
|
||
| **ws-flux-dev** (Flux) | 2201 | 7701 | workpod-flux-network |
|
||
| **workpod-test** (旧测试) | 2223 | 7682 | — |
|
||
|
||
### 6.2 连接速查
|
||
|
||
```bash
|
||
# 基础实例
|
||
Web: http://localhost:7681 # 用户 jc / 密码 1234567
|
||
SSH: ssh root@localhost -p 2222 # 密码 workpod123 (或 ROOT_PASSWORD)
|
||
|
||
# Flux 项目实例
|
||
Web: http://localhost:7701 # 用户 jc / 密码 1234567
|
||
SSH: ssh root@localhost -p 2201 # 密码 workpod123 (或 ROOT_PASSWORD)
|
||
|
||
# 进入容器 (调试用)
|
||
MSYS_NO_PATHCONV=1 docker exec -it workpod-alpine bash
|
||
MSYS_NO_PATHCONV=1 docker exec -it ws-flux-dev bash
|
||
```
|
||
|
||
### 6.3 环境变量速查
|
||
|
||
| 变量 | 默认值 | 用途 |
|
||
|------|--------|------|
|
||
| `ROOT_PASSWORD` | workpod123 | SSH root 密码 |
|
||
| `TTYD_CREDENTIALS` | jc:1234567 | ttyd Web 终端认证 (格式 `用户:密码`) |
|
||
| `TZ` | Asia/Shanghai | 时区 |
|
||
| `JAVA_HOME` | (无) | JDK 路径 (Flux 实例设置) |
|
||
| `MAVEN_HOME` | (无) | Maven 路径 (Flux 实例设置) |
|
||
| `ANTHROPIC_AUTH_TOKEN` | (从宿主机继承) | 智谱 API 密钥 |
|
||
| `ANTHROPIC_BASE_URL` | https://open.bigmodel.cn/api/anthropic | 智谱 API 地址 |
|
||
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | glm-5v-turbo | Sonnet 模型 |
|
||
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | glm-5.1 | Opus 模型 |
|
||
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | glm-4.5-air | Haiku 模型 |
|
||
|
||
---
|
||
|
||
## 7. 开发工具外挂机制
|
||
|
||
### 7.1 支持的工具链
|
||
|
||
entrypoint.sh 启动时自动检测以下路径并加入 PATH：
|
||
|
||
| 工具 | 检测路径 | 环境变量 |
|
||
|------|---------|---------|
|
||
| Java (JDK) | `$JAVA_HOME/bin` | JAVA_HOME |
|
||
| Maven | `$MAVEN_HOME/bin` | MAVEN_HOME |
|
||
| Rust (rustup) | `/root/.cargo/bin` | RUSTUP_HOME, CARGO_HOME |
|
||
| Rust (独立) | `/root/rust-*/bin` | — |
|
||
| Go (gvm) | `/root/gvm/gos/current/bin` | — |
|
||
| Python (pyenv) | `/root/.pyenv/shims`, `.pyenv/bin` | — |
|
||
| Go (自定义) | `/root/go/bin` | GOROOT |
|
||
| 本地工具 | `/root/.local/bin` | — |
|
||
|
||
### 7.2 PATH 生效范围
|
||
|
||
- **当前 entrypoint 进程**：立即 export
|
||
- **后续 shell 登录**：通过 `/etc/profile.d/dev-tools.sh` 自动加载
|
||
- **docker exec**：需要 `bash -lc 'command'` 或手动 source profile
|
||
|
||
### 7.3 使用方式
|
||
|
||
开发者只需将工具安装到对应路径（通过挂载 /root 或在容器内安装），重启或重新登录即可生效。无需修改 Dockerfile 或 entrypoint。
|
||
|
||
---
|
||
|
||
## 8. 多实例部署策略
|
||
|
||
### 8.1 推荐方案
|
||
|
||
```
|
||
项目 A → docker-compose.A.yml (端口 220x / 770x)
|
||
项目 B → docker-compose.B.yml (端口 221x / 771x)
|
||
通用 → docker-compose.yml (端口 2222 / 7681)
|
||
```
|
||
|
||
每个项目一份 compose 文件，基于同一个基础镜像 `workpod-alpine:latest`，通过 Dockerfile 扩展或 volume 挂载添加项目特定依赖。
|
||
|
||
### 8.2 扩展新实例步骤
|
||
|
||
1. 创建 `Dockerfile.xxx`（如需额外包）或直接用基础镜像
|
||
2. 创建 `docker-compose.xxx.yml`（配置端口、挂载、环境变量）
|
||
3. `docker compose -f docker-compose.xxx.yml up -d`
|
||
4. 确认端口不冲突
|
||
|
||
### 8.3 网络隔离
|
||
|
||
每个 compose 文件创建独立的 bridge network，容器间默认不可互通。如需互通可在同一 compose 中定义多 service。
|
||
|
||
---
|
||
|
||
## 9. 安全模型
|
||
|
||
### 9.1 当前状态
|
||
|
||
| 安全项 | 配置 | 风险等级 | 备注 |
|
||
|--------|------|---------|------|
|
||
| **特权模式** | 基础版 `privileged: true` | **高** | Flux 版已移除 |
|
||
| **运行用户** | 全部 root | 中 | 开发环境可接受 |
|
||
| **SSH 登录** | PermitRootLogin yes + 密码 | 中 | 建议生产环境禁用 |
|
||
| **ttyd 认证** | Basic Auth (jc:1234567) | 低-中 | 可配置强密码 |
|
||
| **密码管理** | 环境变量注入 | 低 | 已修复硬编码 |
|
||
| **API Key** | docker-compose env 传递 | 低 | 不写入文件系统 |
|
||
| **镜像源** | alpine:3.23 + npmmirror | 低 | 第三方信任链 |
|
||
| **npm 包** | @latest (不确定版本) | 低 | 用户决策，接受风险 |
|
||
|
||
### 9.2 已修复的问题
|
||
|
||
- ~~密码硬编码在源码中~~ → ROOT_PASSWORD / TTYD_CREDENTIALS 环境变量
|
||
- ~~API Key 写入 .bashrc~~ → docker-compose environment 直接传递
|
||
- ~~healthcheck CMD 数组管道错误~~ → CMD-SHELL + netstat
|
||
- ~~entrypoint 外挂 bind mount~~ → COPY --chmod 内置镜像
|
||
- ~~构建上下文 ~520MB~~ → .dockerignore 优化到 275 bytes
|
||
|
||
### 9.3 待改进项
|
||
|
||
| 优先级 | 改进项 | 建议 |
|
||
|--------|--------|------|
|
||
| P0 | 移除 privileged: true | 基础版改用具体 capability 或确认是否真需要 |
|
||
| P1 | SSH 禁用密码登录 | 改为密钥认证，或限制来源 IP |
|
||
| P2 | ttyd 加密传输 | 前置 nginx/caddy 做 HTTPS 终止 |
|
||
| P3 | npm 包固定版本 | 将 @latest 改为具体版本号，构建可重现 |
|
||
|
||
---
|
||
|
||
## 10. 认证代理 (auth-proxy.js)
|
||
|
||
> 状态：可选组件，已补充到主目录但未默认启用
|
||
|
||
### 10.1 架构
|
||
|
||
```
|
||
浏览器 → :8080 auth-proxy.js
|
||
├── GET /login → 登录页面 (static/login.html)
|
||
├── POST /auth/check → Basic Auth → Token (1h 过期)
|
||
├── GET /api/workspaces → 工作空间列表
|
||
├── GET/WS /* → Token 验证 → 代理到 ttyd :7681
|
||
└── WebSocket upgrade → 双向管道 (终端 I/O)
|
||
```
|
||
|
||
### 10.2 配置
|
||
|
||
| 配置项 | 值 |
|
||
|--------|-----|
|
||
| 监听端口 | 8080 |
|
||
| 认证方式 | Basic Auth (`wk:1234567`, `admin:admin123`) |
|
||
| Token 格式 | `wk_{用户名}_{时间戳}` |
|
||
| Token 过期 | 1 小时 (内存存储) |
|
||
| 工作区路由 | 默认(/) → :7681, hszd → :7682 |
|
||
|
||
### 10.3 生产部署
|
||
|
||
```bash
|
||
# 1. 修改密码（环境变量或配置文件）
|
||
# 2. 前置 Nginx 反向代理 (wk.1216.conf)
|
||
# 3. SSL 证书 (wk.1216.top)
|
||
# 4. 启动
|
||
node auth-proxy.js
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 离线包管理
|
||
|
||
> 状态：归档备用，Dockerfile 直接从 registry 安装
|
||
|
||
### 11.1 包清单
|
||
|
||
| 包名 | 版本 | 用途 | 来源 |
|
||
|------|------|------|------|
|
||
| node-v24.14.1-linux-x64-musl.tar.gz | v24.14.1 | Node.js 运行时 | unofficial-builds.nodejs.org |
|
||
| claude-code-*.tgz | @latest | AI 编程助手 | registry.npmmirror.com |
|
||
| z_ai-coding-helper-*.tgz | @latest | AI 编程助手 | registry.npmmirror.com |
|
||
| openclaw-*.tgz | 2026.3.28 | (未使用) | registry.npmmirror.com |
|
||
| go1.26.1.linux-amd64.tar.gz | 1.26.1 | (外挂预留) | Go 官方 |
|
||
| rust-1.94.1-x86_64-unknown-linux-musl.tar.xz | 1.94.1 | (外挂预留) | Rust 官方 |
|
||
|
||
### 11.2 下载脚本
|
||
|
||
```bash
|
||
./download-packages.sh
|
||
# 自动下载到 packages/ 目录
|
||
# 支持断点续传（文件存在则跳过）
|
||
# 使用国内镜像加速
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 决策记录
|
||
|
||
以下是在项目演进过程中做出的关键架构决策及其原因：
|
||
|
||
### DEC-01: Alpine vs Ubuntu 作为基础镜像
|
||
|
||
- **决策**: 选择 Alpine 3.23
|
||
- **原因**: 镜像小 6 倍（436MB vs 2.6GB）、内存基线低 5 倍、启动快 6 倍
|
||
- **代价**: musl libc 兼容性需注意（JDK 必须用 musl 版本）
|
||
|
||
### DEC-02: JDK/Maven 宿主机挂载 vs 镜像内安装
|
||
|
||
- **决策**: 选择宿主机目录 ro 挂载（`D:/Java/jdk-musl-17`, `D:/Java/maven-mvnd`）
|
||
- **原因**: 升级 JDK/Maven 无需 rebuild 镜像；本地多项目可共享同一套工具链
|
||
- **代价**: 依赖宿主机路径存在；容器不可脱离该主机单独分发
|
||
|
||
### DEC-03: BellSoft Liberica JDK vs 其他 musl JDK
|
||
|
||
- **决策**: BellSoft Liberica JDK 17.0.16+12 (musl)
|
||
- **原因**: Adoptium "musl" 标签实际仍链接 glibc；Alpine openjdk 无法外部挂载；gcompat 缺少符号
|
||
- **参考**: 经 ldd 验证解释器为 `/lib/ld-musl-x86_64.so.1`
|
||
|
||
### DEC-04: npm 包 @latest vs 固定版本
|
||
|
||
- **决策**: 保持 @latest（claude-code 和 coding-helper）
|
||
- **原因**: 用户选择每次构建自动获取最新版本，接受不确定性
|
||
- **风险**: 构建结果可能不一致；回归问题排查困难
|
||
|
||
### DEC-05: auto-upgrade 功能废弃
|
||
|
||
- **决策**: 不实现容器启动时自动检测升级
|
||
- **原因**: 维护负担 > 收益；增加启动复杂度和网络依赖；set -e 下失败处理困难
|
||
- **替代**: 手动 `docker build` 时自然获取最新
|
||
|
||
### DEC-06: workpod-alpine 目录合并到 workpod
|
||
|
||
- **决策**: 删除 `E:/wk-lab/workpod-alpine/`，全部内容归入 `E:/wk-lab/workpod/`
|
||
- **原因**: 单一目录管理；避免两份代码漂移；旧版完整归档于 `_archive/`
|
||
|
||
### DEC-07: entrypoint/ttyd-session 内置镜像 vs bind mount
|
||
|
||
- **决策**: COPY --chmod=755 内置到镜像
|
||
- **原因**: 避免 execvp failed（bind mount 源目录删除后容器失效）；符合 immutable 镜像最佳实践
|
||
- **触发事件**: 2026-04-04 因删除 workpod-alpine 目录导致 workpod 容器 ttyd 子进程全部 crash (exit code 254)
|
||
|
||
---
|
||
|
||
## 附录 A: 常用运维命令
|
||
|
||
```bash
|
||
# 构建
|
||
docker build -t workpod-alpine:latest .
|
||
docker build -t ws-flux-dev:latest -f Dockerfile.flux .
|
||
|
||
# 启动/停止
|
||
docker compose up -d
|
||
docker compose down
|
||
docker compose -f docker-compose.flux.yml up -d
|
||
|
||
# 查看日志
|
||
docker logs -f workpod-alpine
|
||
docker logs --tail 50 ws-flux-dev
|
||
|
||
# 进入容器
|
||
MSYS_NO_PATHCONV=1 docker exec -it workpod-alpine bash
|
||
|
||
# 验证工具链 (需 login shell)
|
||
MSYS_NO_PATHCONV=1 docker exec -it workpod-alpine bash -lc '
|
||
echo "Java: $(java -version 2>&1 | head -1)"
|
||
echo "Maven: $(mvn -version 2>&1 | head -1)"
|
||
echo "Node: $(node -v)"
|
||
echo "Claude: $(claude --version)"
|
||
'
|
||
|
||
# 清理
|
||
docker system prune -f # 清理悬停资源
|
||
docker image prune -f # 清理未使用镜像
|
||
```
|
||
|
||
## 附录 B: 文件总览
|
||
|
||
```
|
||
workpod/
|
||
├── Dockerfile # 基础镜像 (多阶段构建)
|
||
├── Dockerfile.flux # Flux 扩展镜像
|
||
├── entrypoint.sh # 容器入口 (信号/PATH/服务/信息)
|
||
├── ttyd-session.sh # tmux 会话管理
|
||
├── docker-compose.yml # 基础实例 (:2222/:7681)
|
||
├── docker-compose.flux.yml # Flux 实例 (:2201/:7701)
|
||
├── docker-compose-alpine.yml # 备用编排
|
||
├── auth-proxy.js # 认证代理 (可选)
|
||
├── download-packages.sh # 离线包下载 (归档)
|
||
├── entrypoint-test.sh # Test 入口 (归档)
|
||
├── wk.1216.conf # Nginx 配置
|
||
├── nginx-map-patch.sh # Nginx WS 补丁
|
||
├── connection_upgrade.map # Nginx map 片段
|
||
├── .dockerignore # 构建忽略
|
||
├── ISSUES.md # 问题记录
|
||
├── SPECS.md # 本文档 ← 你在这里
|
||
├── docs/
|
||
│ └── 05-问题处理/ # 5 份审核报告
|
||
├── config/ # 配置模板
|
||
├── static/ # auth-proxy 登录页
|
||
├── data/ # 运行时数据
|
||
└── _archive/ # 历史版本归档
|
||
```
|