# 架构设计审核报告 -- WorkPod

> 审核日期：2026-04-07
> 审核范围：`E:/wk-lab/workpod`
> 镜像大小：~436MB（alpine:3.23 基础，多阶段构建）

---

## 架构概览

```
+-----------------------------+       +------------------------+
|  Docker Host (测试服)        |       |  Container             |
|                             |       |  alpine:3.23           |
|  workpod-alpine (2222/7681) |------>|  +--------------------+|
|    docker-compose.yml       |       |  | /usr/sbin/sshd     ||
|    基础实例                 |       |  | ttyd (-W 无认证)   ||
|    workpod-network          |       |  | Node.js (musl)     ||
|                             |       |  | Claude Code @latest||
|                             |       |  | coding-helper     ||
|  ws-flux-dev (2201/7701)    |------>|  | tmux              ||
|    docker-compose.flux.yml  |       |  +--------------------+|
|    Flux 项目实例            |       |                        |
|    Dockerfile.flux 扩展     |       |  /opt/ttyd-session.sh |
|                             |       |  (tmux session 选择)  |
|                             |       |  entrypoint.sh         |
|                             |       |  (开发工具自动检测)    |
|                             |       +------------------------+
|  _archive/auth-proxy.js     |
|  (备用认证代理)              |
|  nginx 反向代理 (wk.1216.top)|
+-----------------------------+

**核心组件关系**：
- **Dockerfile**：多阶段构建（builder 安装 Node.js/npm 包 -> runtime 仅复制产物到 alpine:3.23），entrypoint.sh 和 ttyd-session.sh 通过 `COPY --chmod=755` 内置到镜像
- **entrypoint.sh**：统一入口（已内置镜像），直接 `/usr/sbin/sshd` 启动 SSH，自动检测 /root 下开发工具设置 PATH，ttyd 使用 ttyd-session.sh 做 tmux session 管理
- **Dockerfile.flux**：Flux 项目实例扩展构建，基于基础镜像追加项目特定配置
- **ttyd-session.sh**：独立的会话管理脚本（已通过 `COPY --chmod=755` 内置到镜像），支持 URL 参数 `?session=name` 或交互式菜单选择/创建 tmux session
- **docker-compose.yml**：基础实例编排（context: .），workpod-network 网络，2222/7681 端口
- **docker-compose.flux.yml**：Flux 项目实例编排，2201/7701 端口，挂载 Flux 工作空间
- **docker-compose-alpine.yml**：Alpine 变体备用编排文件，多端口映射（7683/7684），挂载 /root
- **_archive/auth-proxy.js**：Node.js 认证代理（已归档），提供登录页 + token 认证 + 多工作区路由 + WebSocket 代理，作为可选组件保留
- **wk.1216.conf**：Nginx 配置，SSL 终止 + 反向代理到 ttyd

**关键特征**：
- 轻量级镜像（~436MB vs Ubuntu 版 ~2.6GB）
- 单一 entrypoint + Dockerfile 扩展模式：基础实例与项目实例共享核心逻辑，通过 Dockerfile.flux 按需扩展
- 开发工具"外挂"模式：安装到 /root 挂载卷，entrypoint 自动检测
- 认证代理方案（auth-proxy.js）已归档至 _archive/，作为可选组件按需启用

---

## 优势分析

### 1. 多阶段构建 -- 镜像体积控制优秀

builder 阶段完成所有重量级操作（npm install、编译依赖），runtime 阶段仅复制 `/opt/node` 到 `/usr/local`。最终镜像 ~436MB，是 Ubuntu 版的 1/6。这是本项目最突出的架构优势。

### 2. 开发工具"外挂"设计 -- 灵活性高

通过 entrypoint.sh 自动检测 `/root` 下的 `.cargo`、`.pyenv`、`go`、`.local/bin` 等目录并动态设置 PATH，实现了：
- 工具安装与镜像构建解耦
- 不同实例可安装不同工具集
- 容器重建不丢失手动安装的工具（只要 /root 已挂载）
- 新增工具类型只需在 entrypoint 添加一行检测逻辑

这一设计在 ISSUES.md 中有清晰记录，体现了"踩坑 -> 抽象 -> 文档化"的良好工程实践。

### 3. ttyd-session.sh -- 会话管理解耦

将 ttyd 的启动命令从 entrypoint 中抽离为独立脚本 `ttyd-session.sh`：
- 支持 URL 参数快速进入指定 session（`?session=xxx`）
- 交互式菜单列出已有 session 并支持新建
- session 名安全过滤（仅允许字母数字下划线连字符）
- 共享 attach 模式（不加 `-d`，多人可同时查看同一 session）

职责划分清晰：entrypoint 负责服务启停，ttyd-session 负责终端会话逻辑。

### 4. 问题记录完整 (ISSUES.md)

ISSUES.md 记录了 11 个已解决的问题及解决方案，涵盖：
- Alpine 特有命令差异（ss vs netstat）
- BuildKit 兼容性（--chmod、缓存行为）
- 运行时问题（中文输入、断线恢复、数据持久化）
- 架构决策记录（/root 安装原则）

这是非常有价值的知识资产，降低了团队其他成员的踩坑成本。

### 5. auth-proxy.js -- 完整的认证层

虽然未默认集成到容器中，但 auth-proxy.js 提供了：
- Basic Auth 登录 + Token 机制
- 内存 Token 存储（1小时过期）
- 多工作区路由（默认 + hszd）
- HTTP 和 WebSocket 双协议代理
- 自定义登录页面

这为生产化部署提供了现成的安全方案。

---

## 问题与建议

### [严重] 多实例 entrypoint 膨胀与维护噩梦 -- **[已解决]**

- **位置：** 原为 `entrypoint.sh` vs `entrypoint-test.sh`
- **现状：**
  - `entrypoint-test.sh` 已归档至 `_archive/`
  - 当前仅保留单一 `entrypoint.sh` 作为统一入口
  - Flux 项目实例通过 `Dockerfile.flux` 扩展构建，不再需要独立 entrypoint
- **原问题描述：**
  1. **代码大量重复**：两个文件约 70% 代码完全相同（信号处理、PATH 检测、sshd 启动、健康检查、启动信息打印）。修改公共逻辑需要同步两处
  2. **yxl 实例的 entrypoint 未纳入仓库**：该实例应该还有第三个 entrypoint 变体，但仓库中只有两个
  3. **每新增一个用户就要复制一份 entrypoint**：当前 2 个文件，如果有 10 个用户就是 10 个几乎相同的脚本
  4. **配置散落在脚本内部**：ttyd 凭据、端口号、用户名等硬编码在不同 entrypoint 中
- **解决方案：** 归档 entrypoint-test.sh，统一使用单一 entrypoint.sh + Dockerfile 扩展模式。项目特定配置通过 Dockerfile.flux 注入，无需维护多份 entrypoint。
- **遗留建议（供参考）：** 如未来需支持更多定制化实例，可考虑将差异项外部化为环境变量：
  ```bash
  # entrypoint.sh 统一入口
  TTYD_CREDENTIALS="${TTYD_CREDENTIALS:-ada:123}"
  TTYD_PORT="${TTYD_PORT:-7681}"
  SSH_PORT="${SSH_PORT:-22}"
  CREATE_DEVELOPER_USER="${CREATE_DEVELOPER_USER:-false}"
  DEVELOPER_NAME="${DEVELOPER_NAME:-developer}"

  [ "$CREATE_DEVELOPER_USER" = "true" ] && setup_developer_user
  ```

### [高] 安全凭据硬编码且各实例不一致 -- **[已修复]**

- **位置：** 原为 `entrypoint.sh:45`, `entrypoint-test.sh:93`, `Dockerfile:34`
- **现状：** 所有凭据已统一通过环境变量注入，不再在各文件中硬编码
- **原问题描述：**

  | 凭据类型 | 原始状态 | 当前状态 |
  |----------|---------|---------|
  | root 密码 | 多处硬编码 workpod123 | 环境变量注入 |
  | ttyd 凭据 | 各实例不一致（ada:123 / jc:1234567） | 环境变量统一注入 |
  | auth-proxy 密码 | JS 源码明文 | 已随 auth-proxy 归档，按需启用时从配置读取 |

- **原问题：**
  1. **密码明文写在 4 个不同文件中**，修改密码需要改多处
  2. **ttyd 凭据各实例不同**（ada:123 vs jc:1234567），但没有统一的管理方式
  3. **auth-proxy.js 的密码是 JS 源码中的明文**，如果该文件被包含在镜像或 Web 目录中则直接暴露
  4. **root 密码与 Dockerfile 中 chpasswd 一致**，但如果通过环境变量覆盖 entrypoint 的密码，Dockerfile 层的密码仍然存在
- **解决方案：** 统一通过 docker-compose 环境变量或 `.env` 文件注入所有凭据，清除源码中的硬编码值。

### [中] auth-proxy.js 与容器架构脱节

- **位置：** `_archive/auth-proxy.js`, `static/login.html`, `wk.1216.conf`
- **现状：** auth-proxy.js 已归档至 `_archive/` 目录，作为可选组件保留在主目录中。不再作为核心组件强制集成。
- **问题：**
  1. **部署方式需明确**：如需启用 auth-proxy，应补充启动说明（手动 / systemd / compose sidecar）
  2. **生命周期无保障**：若独立进程运行，容器重启后 auth-proxy 不会自动恢复
  3. **token 存储在内存中**：auth-proxy 重启后所有用户需重新登录（可接受，但应文档化）
  4. **工作区配置硬编码**：`WORKSPACES` 数组写死记录，新增工作区需改代码重启
  5. **与 ttyd -W 标志冲突**：容器内 ttyd 启动时用了 `-W`（禁用重连提示，非认证），如果 auth-proxy 作为唯一入口则需确保 ttyd 端口不对外暴露
- **建议：**
  - 如需正式使用：将 auth-proxy 集成到 docker-compose 中作为 sidecar 容器或独立 service
  - 或将认证能力内置到容器内（如 ttyd 加 `-c` 参数 + Nginx basic_auth）
  - 工作区配置改为从环境变量或 JSON 文件读取
  - 在 README 中说明 auth-proxy 的启用方式和适用场景

### [中] 编排文件职责需明确

- **位置：** `docker-compose.yml`, `docker-compose.flux.yml`, `docker-compose-alpine.yml`
- **现状：** 当前有 3 个编排文件：
  - **`docker-compose.yml`**：基础实例，2222/7681 端口，挂载 workspace，4G 内存限制，workpod-network 网络。适用于通用开发环境。
  - **`docker-compose.flux.yml`**：Flux 项目专用实例，2201/7701 端口，挂载 Flux 工作空间目录，使用 Dockerfile.flux 扩展构建。适用于 Flux 项目开发。
  - **`docker-compose-alpine.yml`**：Alpine 变体备用编排，2222/7683+7684 端口，挂载 workspace + /root，无资源限制。适用于需要完整 /root 挂载的调试场景。
- **问题：**
  1. 三个文件用途已有区分但未在文档中集中说明
  2. `docker-compose-alpine.yml` 直接引用镜像而非构建，与另外两个文件的构建模式不一致
  3. 缺少 `.env` 文件或参数化配置来统一管理端口/资源等差异
- **建议：**
  - 在 README 中补充各编排文件的用途说明和使用场景
  - 考虑合并为单一 compose 文件 + profiles，或保持多文件但统一 `.env` 参数化

### [中] Claude Code 版本在 download-packages.sh 中滞后 -- **[已解决]**

- **位置：** 原为 `download-packages.sh:33` vs `Dockerfile:18`
- **现状：** 已统一使用 `@latest` 标签，不再锁定具体版本号
- **原问题描述：**
  - download-packages.sh：`claude-code@2.1.87`
  - Dockerfile：`@anthropic-ai/claude-code@2.1.89`
- **原问题：** 下载脚本中的版本落后于 Dockerfile 实际使用的版本。如果有人先执行下载脚本再构建，会得到错误的包。
- **解决方案：** 改用 `@latest` 标签，消除版本不一致问题。每次构建自动拉取最新版。

### [中] dev-tools PATH 检测逻辑重复

- **位置：** `entrypoint.sh:19-29`（运行时 export） vs `entrypoint.sh:32-40`（profile.d 写入）
- **现状：** 开发工具目录检测逻辑出现 2 次（单一 entrypoint.sh 内：一次 export 一次写入 profile.d）。原为 4 处（两个 entrypoint 各两次），归档 entrypoint-test.sh 后已减少至 2 处。
- **问题：** 违反 DRY 原则。新增一种工具类型需要修改 2 处。
- **建议：** 抽取为函数或独立脚本：
  ```bash
  # /opt/lib/dev-tools.sh
  setup_dev_paths() {
      local profile=""
      [ -d /root/.cargo/bin ] && { export PATH="/root/.cargo/bin:$PATH"; profile+="..."; }
      # ...
      [ -n "$profile" ] && echo "$profile" > /etc/profile.d/dev-tools.sh
  }
  ```

### [低] packages/ 目录包含未在 Dockerfile 中使用的包

- **位置：** `packages/go1.26.1.linux-amd64.tar.gz`, `packages/rust-1.94.1-x86_64-unknown-linux-musl.tar.xz`
- **现状：** packages/ 目录中有 Go 和 Rust 的 musl 构建包，但 Dockerfile 仅安装了 Node.js + npm 包
- **问题：**
  1. 占用 ~247MB 磁盘空间
  2. download-packages.sh 也没有下载这两个包的步骤（说明可能是手动放入的）
  3. PACKAGES.md 不存在（Alpine 版缺少此文档），无法确认这些包的用途
- **建议：**
  - 如果是为"开发工具外挂"模式准备的：在文档中明确说明
  - 如果不再需要：清理掉以减小仓库体积
  - 补充 PACKAGES.md 说明软件包策略

### [低] entrypoint-test.sh 中的 Claude Code 别名策略不一致

- **位置：** `entrypoint-test.sh:65` vs `entrypoint-test.sh:76`
- **现状：**
  - developer 用户：`alias claude='claude --dangerously-skip-permissions'`
  - root 用户：`alias claude='claude --allow-dangerously-skip-permissions'`
- **问题：**
  1. root 用 `--allow-dangerously-skip-permissions`，developer 用 `--dangerously-skip-permissions`，参数不同但效果类似，容易混淆
  2. 注释说"root 禁止 --dangerously-skip-permissions"，但这应该是 Claude Code 对 root 用户的限制而非 CLI 参数限制
  3. 这个别名仅在 bashrc 中，非交互式 shell（如 `docker exec` 执行命令）不会加载
- **建议：** 统一别名策略或在注释中更清晰地解释原因差异。考虑用 wrapper 脚本替代 alias 以覆盖所有调用场景。

### [低] ttyd-session.sh 的 CHOICE 输入无超时

- **位置：** `ttyd-session.sh:37`
- **现状：** `read -p "session: " CHOICE` 无超时设置
- **问题：** 如果用户打开 Web 终端但不输入选择，read 会一直阻塞。在自动化场景或意外断开的情况下可能导致僵尸进程。
- **建议：** 添加 `-t 30` 超时（30秒），超时后自动选择 default session。

---

## 架构改进路线图

### P0 -- 紧急（影响安全与可维护性）

| 序号 | 改进项 | 工作量 | 说明 |
|------|--------|--------|------|
| 1 | entrypoint 配置驱动重构 | 3h → **降低优先级** | 单 entrypoint 场景下紧迫性下降。当前 entrypoint.sh + Dockerfile.flux 扩展模式已满足需求，配置驱动重构可作为 P2 优化项储备 |
| 2 | 凭据外部化管理 | **[已完成]** | 所有密码/密钥已通过环境变量注入，清除源码中的硬编码 |
| 3 | auth-proxy 集成到编排体系 | 2h | auth-proxy 已归档为可选组件。如需正式启用，编写 docker-compose 或 systemd unit 确保生命周期受控 |

### P1 -- 重要（提升工程质量）

| 序号 | 改进项 | 工作量 | 说明 |
|------|--------|--------|------|
| 4 | dev-tools 检测逻辑去重 | 1h | 抽取为共享函数/脚本，消除 2 处重复（原 4 处） |
| 5 | 版本号单一数据源 | **[已完成]** | 已统一使用 @latest 标签 |
| 6 | 编排文件职责文档化 | 1h | 明确 3 个 yml 文件（yml / .flux.yml / -alpine.yml）的用途和使用场景，补充 README 说明 |

### P2 -- 优化（改善体验）

| 序号 | 改进项 | 工作量 | 说明 |
|------|--------|--------|------|
| 7 | 补充 PACKAGES.md | 0.5h | 说明 Alpine 版的包策略（含 Go/Rust 预留包） |
| 8 | 清理冗余包或文档化 | 0.25h | 决定 packages/ 中 Go/Rust 包的去留 |
| 9 | ttyd-session 超时保护 | 0.15h | read 添加超时 |
| 10 | Claude Code alias 统一 | 0.25h | 明确策略或改为 wrapper 脚本 |

---

## 两版本协同改进建议

由于 WorkPod Ubuntu 版依赖 Alpine 版的 entrypoint 脚本，两个版本的改进应协调进行：

### 共享资产清单

| 资产 | 当前归属 | 建议归属 |
|------|---------|---------|
| entrypoint.sh (核心逻辑) | Alpine 版（Ubuntu 版引用） | 提取为共享模块 |
| ttyd-session.sh | Alpine 版（Ubuntu 版引用） | 提取为共享模块 |
| PACKAGES.md | 仅 Ubuntu 版有 | 两版本都应有 |
| auth-proxy.js | Alpine 版（独立运行） | 可供两版本共用 |
| ISSUES.md | 仅 Alpine 版有 | Ubuntu 版也应建立 |

### 推荐的共享方案

```
workpod-common/            # 新建共享仓库或目录
  ├── entrypoint-core.sh   # 公共逻辑（信号处理、sshd、健康检查）
  ├── ttyd-session.sh      # 会话管理（已有，可直接复用）
  ├── lib-dev-tools.sh     # 开发工具检测函数
  └── versions.env         # 版本号定义（NODE_VERSION=, CLAUDE_CODE_VERSION= ...）

workpod/                    # Ubuntu 版
  ├── entrypoint.sh         # source core + Ubuntu 特定逻辑
  └── Dockerfile            # ubuntu 构建

workpod-alpine/             # Alpine 版
  ├── entrypoint.sh         # source core + Alpine 特定逻辑
  ├── entrypoint-test.sh    # source core + test 实例特定逻辑
  └── Dockerfile            # alpine 多阶段构建
```

---

## 总结评价

WorkPod 的架构质量持续改善。多阶段构建、开发工具外挂设计、ttyd-session 解耦、完整的问题记录都是亮点。~436MB 的镜像是务实的选择 -- 在功能完备性和体积之间取得了良好平衡。

本次审核中，多项历史问题已得到解决或修复：
- **entrypoint 膨胀问题 [已解决]**：归档 entrypoint-test.sh，统一单一 entrypoint.sh + Dockerfile.flux 扩展模式
- **安全凭据硬编码 [已修复]**：统一通过环境变量注入
- **Claude Code 版本滞后 [已解决]**：改用 @latest 标签

当前架构已从"多实例复制 entrypoint"模式演进为"单入口 + 构建扩展"模式，可维护性显著提升。P0-1（entrypoint 配置驱动重构）的紧迫性随之降低，可作为 P2 优化项储备。

安全层面，auth-proxy.js 已归档至 `_archive/` 作为可选组件保留。如需正式启用认证层，建议按 P0-3 方案集成到编排体系中。

整体而言，WorkPod 已整合为主目录项目，Alpine 作为基础镜像方案继续演进，Flux 等项目实例通过 Dockerfile.flux 按需扩展。