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

2026-07-27 13:59:18 +08:00
parent feb76081a0
commit ccca0fa62b
51 changed files with 6125 additions and 993 deletions
@@ -0,0 +1,352 @@
+# 安全性审核报告 (WorkPod Alpine)
+
+> 审核日期：2026-04-07
+> 审核范围：Dockerfile、entrypoint.sh、ttyd-session.sh、docker-compose.yml、auth-proxy.js、ISSUES.md
+
+---
+
+## 审核概要
+
+| 严重等级 | 数量 |
+|---------|------|
+| 严重 (Critical) | 1 (S-02) |
+| 高危 (High) | 3 (H-02, H-03, H-04, H-05, H-06) |
+| 中危 (Medium) | 5 (S-01[降级], M-01~M-05) |
+| 低危 (Low) | 5 (L-01~L-05) |
+
+**总计：21 项安全问题（其中 S-01/S-03/S-04/H-01/M-06 已修复/改进/不适用）**
+
+---
+
+## 问题清单
+
+### [中危] S-01: 硬编码密码明文存储在源码中 **[已修复]**
+
+- **位置：**
+  - `Dockerfile:34` — `echo 'root:${ROOT_PASSWORD}' | chpasswd` （构建时仍保留默认值）
+  - `entrypoint.sh` — ttyd 密码通过 `${TTYD_CREDENTIALS:-jc:1234567}` 环境变量注入
+- **描述：** ~~所有认证凭证均以明文硬编码在源码文件中~~ → **已修复**：密码现已通过环境变量 `${ROOT_PASSWORD}` 和 `${TTYD_CREDENTIALS:-jc:1234567}` 注入，`entrypoint.sh` 不再硬编码密码。但需注意 `Dockerfile:34` 的 `chpasswd` 仍保留默认值（构建时），运行时通过环境变量覆盖。
+- **影响：** 攻击者获取源码不再直接获得运行时凭据。降级为 **[中危]**：Dockerfile 构建时默认值仍存在，但运行时可被 env 覆盖。
+- **建议修复：**
+  1. Dockerfile 中 chpasswd 也改为环境变量引用或移除默认值
+  2. 将 `.env` 文件加入 `.gitignore`，使用 `docker-compose --env-file` 加载
+  3. 对已提交的密码执行 `git filter-branch` 或 BFG 清理历史
+  4. 若密码已泄露，立即轮换所有凭证
+
+### [严重] S-02: privileged: true 特权模式运行
+
+- **位置：**
+  - `docker-compose.yml:11` — `privileged: true`
+  - `docker-compose-alpine.yml:7` — `privileged: true`
+- **描述：** 容器以特权模式运行，拥有宿主机全部 capabilities（包括 SYS_ADMIN、NET_ADMIN 等），可访问所有设备文件（/dev/*），可修改内核参数，可逃逸到宿主机。
+- **影响：** 容器内任何代码执行均可直接控制宿主机操作系统。结合 root 用户 + 全权限 Claude 配置，AI 工具的任意命令执行等同于宿主机 root 权限。
+- **建议修复：**
+  1. 评估是否真的需要特权模式。若仅需要 Docker-in-Docker，使用 `docker.sock` 挂载替代
+  2. 若必须使用特权模式，限制为最小必要 capabilities（如仅 `SYS_PTRACE`）
+  3. 考虑使用 `--security-opt=no-new-privileges` 防止权限提升
+  4. 在生产环境中绝对禁止特权模式
+
+### [严重] S-03: Claude Code settings.json 设置 allow: ["*"] — 无限制全权限 **[不适用当前版本]**
+
+- **位置：**
+  - ~~`entrypoint-test.sh:41-48`~~ — 已归档到 `_archive/`
+  - ~~`entrypoint-test.sh:51-58`~~ — 已归档到 `_archive/`
+  - ~~`config/test-claude-settings.json`~~ — 外部配置文件同样 allow: ["*"]
+- **描述：** ~~Claude Code 的 permissions 配置设置为 `allow: ["*"]`~~ → **不适用当前版本**：`entrypoint-test.sh` 已归档到 `_archive/` 目录，当前主 `entrypoint.sh` 中无此 `allow: ["*"]` 配置。
+- **影响：** 当前版本不受此问题影响。
+- **建议修复：** 若后续重新启用类似配置，应遵循最小权限原则。
+
+### [严重] S-04: API 密钥 (ANTHROPIC_AUTH_TOKEN) 通过环境变量暴露给所有进程 **[已修复]**
+
+- **位置：**
+  - ~~`entrypoint-test.sh:67`~~ — ~~写入 .bashrc~~ → 已修复
+  - ~~`entrypoint-test.sh:68`~~ — ~~写入 .bashrc~~ → 已修复
+- **描述：** ~~API 密钥写入 .bashrc 并全局暴露~~ → **已修复**：当前版本通过 `docker-compose.yml` 的 `environment` 直接传递 `ANTHROPIC_AUTH_TOKEN` 等环境变量，不再写入 `.bashrc`。
+- **影响：** 密钥不再持久化到 `.bashrc`，不再对所有登录用户自动暴露。但容器内子进程仍可通过 `/proc/*/environ` 读取（Docker 环境变量的固有特性）。
+- **建议修复：**
+  1. 使用 Docker secrets 或外部密钥管理服务进一步加固
+  2. 限制密钥文件的权限为 `chmod 600`
+
+---
+
+### [高] H-01: developer 用户 NOPASSWD sudo 全权限 **[不适用当前版本]**
+
+- **位置：** ~~`entrypoint-test.sh:34`~~ — 已归档到 `_archive/`
+- **描述：** ~~developer 用户配置了无需密码的 sudo 全权限~~ → **不适用当前版本**：`entrypoint-test.sh` 已归档到 `_archive/` 目录，当前主 `entrypoint.sh` 中无此配置。
+- **影响：** 当前版本不受此问题影响。
+
+### [高] H-02: SSH 允许 root 密码登录 + 弱密码
+
+- **位置：**
+  - `Dockerfile:35` — `PermitRootLogin yes`
+  - `Dockerfile:34` — `chpasswd` 设置密码（默认 workpod123，可通过 `${ROOT_PASSWORD}` 覆盖）
+- **描述：** SSH 服务配置为允许 root 用户使用密码登录（而非仅密钥认证）。**降级说明**：`ROOT_PASSWORD` 现在可通过环境变量覆盖，默认值仍为 `workpod123` 但可自定义。端口 22 映射到宿主机 2222 端口，对外可达。
+- **影响：** 若用户未自定义 `ROOT_PASSWORD`，暴力破解攻击仍可在短时间内猜出默认密码。一旦成功，攻击者获得容器 root shell，在特权模式下进一步控制宿主机。
+- **建议修复：**
+  1. 禁用密码登录：`PasswordAuthentication no`，仅允许密钥认证
+  2. 若必须保留密码登录，通过环境变量设置强密码（20+ 字符随机生成）
+  3. 限制 SSH 来源 IP（防火墙规则）
+  4. 考虑使用 fail2ban 防暴力破解
+  5. 更改默认 SSH 端口（虽属隐匿安全但有一定价值）
+
+### [高] H-03: ttyd 使用 Basic Auth 且密码强度不足 **[已改进]**
+
+- **位置：**
+  - `entrypoint.sh` — ttyd 密码通过 `${TTYD_CREDENTIALS:-jc:1234567}` 环境变量配置
+- **描述：** ttyd 使用 `-c` 参数启用 HTTP Basic Authentication。**已改进**：默认凭据改为 `jc:1234567` 通过环境变量 `TTYD_CREDENTIALS` 配置，不再硬编码在 entrypoint.sh 中。仍存在的风险：
+  1. 默认密码仍偏弱（7位数字/字母组合）
+  2. Basic Auth 凭据以 Base64 编码传输（非加密），中间人可截获
+  3. 未强制 HTTPS，密码明文传输
+  4. ttyd `-c` 参数在 Safari 浏览器中存在兼容性问题（已知 Safari 不支持 ttyd 内置 Basic Auth）
+  5. Web 终端端口（7681）暴露，增加攻击面
+- **影响：** 默认密码可被暴力破解；未加密传输可被网络嗅探；浏览器兼容性问题可能迫使降级安全措施。
+- **建议修复：**
+  1. 通过 TTYD_CREDENTIALS 环境变量设置强密码（16+ 字符随机字符串）
+  2. 在前端加反向代理（nginx/caddy）终止 TLS
+  3. 考虑使用 auth-proxy.js 作为认证层（已有实现），但需修复其自身安全问题
+  4. 限制 ttyd 端口的网络访问范围
+
+### [高] H-04: 多实例共享网络 (workpod-network) 缺乏隔离
+
+- **位置：** `docker-compose-alpine.yml:23-24` — `name: workpod-network`
+- **描述：** 测试服多个 WorkPod 实例共享同一个 Docker 网络 `workpod-network`。这意味着：
+  1. 同一网络内的容器可以互相访问对方的开放端口
+  2. 一个容器被攻陷后，可作为跳板攻击同网络其他容器
+  3. 容器间通信不经过宿主机防火墙
+- **影响：** 横向移动风险——单点突破导致整个开发环境沦陷。
+- **建议修复：**
+  1. 为每个实例创建独立网络
+  2. 若需共享数据，使用专用数据卷而非网络共享
+  3. 在容器内部使用 iptables/nftables 限制容器间流量
+  4. 考虑 Docker network 的 `internal` 选项禁止外部访问
+
+### [高] H-05: auth-proxy.js 存在多处安全隐患
+
+- **位置：** `auth-proxy.js` 全文（已从 `_archive/` 补充回主目录）
+- **描述：** 认证代理脚本存在以下安全问题：
+  1. **第8行**：密码硬编码在源码中 `{ wk: '1234567', admin: 'admin123' }`
+  2. **第15行**：Token 存储在内存 Set 中，无持久化，重启后所有 token 失效（可用性问题），但也意味着无法审计
+  3. **第19行**：Token 生成方式可预测（`wk_用户名_时间戳`），格式固定且时间戳精度为毫秒，可被枚举猜测
+  4. **第77-89行**：Basic Auth 凭据仅做 Base64 解码比对，无速率限制，可被暴力破解
+  5. **第103-105行**：`/token` 和 `/ttyd/` 路径绕过 token 验证直接代理到默认工作区，形成认证旁路
+  6. **第49行**：代理请求时透传原始 headers（含 Authorization），可能导致凭据泄漏到后端
+- **影响：** 认证层形同虚设，token 可被猜测/绕过，密码可被暴力破解，凭据可能泄漏到后端服务。
+- **建议修复：**
+  1. Token 使用 crypto.randomBytes() 生成不可预测的随机 token
+  2. `/token` 和 `/ttyd/` 端点也必须验证 token
+  3. 添加登录失败速率限制（如每 IP 每分钟最多5次）
+  4. 过滤敏感 header（Authorization、Cookie）不转发到后端
+  5. 密码使用环境变量或外部配置，不从源码读取
+
+### [高] H-06: /root 目录挂载到宿主机 (docker-compose-alpine.yml)
+
+- **位置：** `docker-compose-alpine.yml:20` — `./data/workpod-alpine/root:/root`
+- **描述：** 将容器的 `/root` 目录 bind mount 到宿主机目录。这意味着：
+  1. 容器内的 root 用户 home 目录内容直接暴露在宿主机文件系统上
+  2. 包含 .claude/settings.json（含全权限配置）、.bashrc（含 API 密钥）、ssh 密钥等敏感信息
+  3. 宿主机上其他进程/用户可能有权读取这些文件
+  4. 容器内对 /root 的修改直接影响宿主机
+- **影响：** 敏感配置和密钥在宿主机上的安全性取决于宿主机文件系统权限，增加了攻击面。
+- **建议修复：**
+  1. 评估是否确实需要挂载 /root，若仅为持久化工具安装，考虑只挂载子目录
+  2. 设置挂载目录的严格文件权限（chmod 700）
+  3. 确保 /root 下的密钥文件权限为 600
+
+---
+
+### [中] M-01: heredoc 注入风险（部分已缓解）
+
+- **位置：**
+  - `entrypoint-test.sh:41-48` — `cat > /root/.claude/settings.json << 'SETTINGS'` （已用引号包裹，安全）
+  - `entrypoint-test.sh:64-71` — `cat > /home/developer/.bashrc << BASHRC` （**未用引号包裹，有风险**）
+  - `entrypoint-test.sh:75-77` — `cat > /root/.bashrc << 'ROOTRC'` （已用引号包裹，安全）
+  - `entrypoint-test.sh:80-88` — `cat > /etc/profile.d/dev-tools.sh << 'PROFILE'` （已用引号包裹，安全）
+- **描述：** `entrypoint-test.sh:64` 的 heredoc 定界符 `BASHRC` 未加引号，这意味着 heredoc 内容中的变量（`${ANTHROPIC_AUTH_TOKEN}`、`${ANTHROPIC_BASE_URL}` 等）会被 shell 展开。虽然当前内容是期望的行为（需要展开环境变量），但如果将来有人在此处添加包含特殊字符的用户输入，可能导致注入。
+- **影响：** 当前风险较低（变量值来自受控的环境变量），但编码模式不规范，未来维护可能引入漏洞。
+- **建议修复：**
+  1. 保持现状但添加注释说明此处有意使用未引用 heredoc 以展开变量
+  2. 或者改用双引号定界符 `"BASHRC"` 并显式使用 `${VAR}` 引用变量
+
+### [中] M-02: ttyd-session.sh 命令注入风险（已部分缓解）
+
+- **位置：** `ttyd-session.sh:9` — `SESSION_NAME=$(echo "$TTYD_QUERY_STRING" | tr '&' '\n' | grep '^session=' | head -1 | cut -d= -f2)`
+- **描述：** 从 URL query string 提取 session 名称时，虽然第55行做了过滤（`tr -cd 'a-zA-Z0-9_\-'`），但在第37行的 `read` 命令中，用户交互输入的 `CHOICE` 变量在第44-46行被用于 `sed -n "${CHOICE}p"`，如果 CHOICE 包含恶意内容（如 `1; rm -rf /`），虽然 grep 数字检查提供了一定保护，但防御不够严谨。
+- **影响：** 攻击者可能通过构造特殊的 session 名称或交互输入来注入命令。当前有 `tr -cd` 过滤和数字匹配作为缓解措施，降低了但未消除风险。
+- **建议修复：**
+  1. 在 read 后立即对 CHOICE 做输入验证
+  2. 使用 `[[ "$CHOICE" =~ ^[0-9]+$ ]]` 替代 `grep -qE` 做更严格的数字判断
+  3. 使用数组索引代替 sed 行号引用
+
+### [中] M-03: 缺少 .gitignore 导致敏感文件可能被提交
+
+- **描述：** 项目根目录不存在 `.gitignore` 文件。以下敏感文件/目录可能被意外提交到 Git 仓库：
+  - `data/` — 可能包含工作区数据和挂载的 /root 内容
+  - `config/test-claude-settings.json` — 含全权限配置
+  - `packages/` — 可能包含二进制包
+  - `*.tar.gz` — `workpod-alpine-latest.tar.gz` 镜像导出文件
+  - `wk.1216.conf` — 可能含 nginx/服务器配置
+- **影响：** 敏感数据（工作区代码、配置、镜像）泄露到 Git 仓库。
+- **建议修复：** 创建 `.gitignore` 文件，至少排除：`data/`、`*.tar.gz`、`.env*`、`config/*.json`
+
+### [中] M-04: Alpine 镜像使用第三方镜像源 (mirrors.aliyun.com)
+
+- **位置：** `Dockerfile:6`、`Dockerfile:28` — `sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g'`
+- **描述：** 构建过程中将 Alpine 官方包源替换为阿里云镜像源。虽然这是常见的国内加速做法，但引入了第三方信任链：
+  1. 包完整性依赖阿里云镜像的同步正确性
+  2. 中间人攻击面扩大（DNS 劫持、镜像源被入侵）
+  3. 生产环境构建应优先使用官方源或可信的企业镜像
+- **影响：** 若镜像源被污染，可能在构建阶段植入恶意软件到最终镜像中（供应链攻击）。
+- **建议修复：**
+  1. 构建时使用 `--no-cache` 并验证包签名
+  2. 考虑使用官方源配合网络代理
+  3. 至少在生产发布构建中使用官方源
+
+### [中] M-05: 容器缺少资源隔离和安全增强配置
+
+- **位置：** `docker-compose.yml`、`docker-compose-alpine.yml`
+- **描述：** 容器配置缺少以下安全加固措施：
+  1. 未设置 `read_only: true` — 容器文件系统可写
+  2. 未设置 `security_opt: ["no-new-privileges:true"]` — 进程可通过 setuid/setgid 提权
+  3. 未设置 `cap_drop: [ALL]` + `cap_add: [特定能力]` — 保留全部 Linux capabilities
+  4. 未设置 `user:` — 默认以 root 运行
+  5. 未设置 `tmpfs: /tmp, /dev/shm` — 临时目录使用容器默认挂载
+- **影响：** 容器逃逸向量增多，进程提权路径未被阻断。
+- **建议修复：**
+  1. 添加 `security_opt: ["no-new-privileges:true"]`
+  2. 添加 `cap_drop: [ALL]` 仅保留必要能力
+  3. 考虑以非 root 用户运行主进程
+  4. 对 /tmp 等可写目录使用 tmpfs 并设置 `exec` 选项防止脚本执行
+
+### [中] M-06: 日志和启动信息泄露敏感配置 **[已修复]**
+
+- **位置：**
+  - ~~`entrypoint.sh:76-78`~~ — ~~打印连接方式和密码~~ → 已修复
+  - ~~`entrypoint-test.sh:124-126`~~ — ~~打印连接方式和密码~~ → 已归档
+- **描述：** ~~启动时将连接地址和密码输出到 stdout/stderr~~ → **已修复**：当前 `entrypoint.sh` 不再打印密码。
+- **影响：** `docker logs` 不再泄露密码。
+- **建议修复：** 无需进一步操作。
+
+---
+
+### [低] L-01: HEALTHCHECK 命令不一致
+
+- **位置：**
+  - `Dockerfile:49` — `netstat -tlnp`
+  - `docker-compose.yml:48` — `ss -tlnp | grep ...`
+- **描述：** Dockerfile 中的 HEALTHCHECK 使用 `netstat`（ISSUES.md 已记录 ss 不可用的问题），而 docker-compose.yml 中覆盖使用了 `ss` 命令。根据 ISSUES.md 记录，Alpine 中 `ss` 不可用（需要安装 iproute2），compose 中的 healthcheck 会因 `ss: not found` 而持续失败。
+- **影响：** 健康检查不准确，可能导致编排系统错误判断容器状态。
+- **建议修复：** 统一使用 `netstat -tlnp` 或安装 `iproute2` 后统一使用 `ss`。
+
+### [低] L-02: EXPOSE 指令声明过多端口
+
+- **位置：** `Dockerfile:46` — `EXPOSE 22 7681`
+- **描述：** Dockerfile 中声明暴露 22 (SSH) 和 7681 (ttyd) 端口。EXPOSE 主要是文档作用，但会给使用者错误的暗示。实际上 compose 文件映射了更多端口（2222-2226, 7681-7686）。
+- **影响：** 信息误导，但不构成直接安全威胁。
+- **建议修复：** 更新 EXPOSE 为实际使用的端口集合，或在注释中说明。
+
+### [低] L-03: npm registry 使用第三方镜像源
+
+- **位置：** `Dockerfile:17` — `npm config set registry https://registry.npmmirror.com`
+- **描述：** npm 安装使用淘宝镜像源（npmmirror.com）。与 APK 镜像源类似，这引入了第三方供应链信任问题。
+- **影响：** npm 包可能被篡改（供应链攻击），尤其 `@anthropic-ai/claude-code` 是核心依赖。
+- **建议修复：** 生产构建使用官方 npm registry，或启用 npm 校验（`npm config set verify-signature true`）。
+
+### [低] L-04: 镜像中包含不必要的构建工具痕迹
+
+- **位置：** `Dockerfile:38` — `COPY --from=builder /opt/node /usr/local`
+- **描述：** 多阶段构建是好的实践（builder 阶段的缓存和构建工具不会进入最终镜像），但最终镜像仍然较大（约 436MB）。应确认是否有不必要的文件被复制。
+- **影响：** 攻击面增大（更多二进制文件 = 更多潜在漏洞），拉取/分发效率降低。
+- **建议修复：**
+  1. 审查 `/opt/node` 下是否包含不必要的文件（文档、测试等）
+  2. 考虑使用 `COPY --from=builder /opt/node/bin /usr/local/bin` 仅复制必要文件
+  3. 使用 `docker scout` 分析镜像内容
+
+### [低] L-05: Windows 伪影文件残留 **[风险降低]**
+
+- **描述：** 项目目录中发现以下 Windows 伪影文件：
+  - `entrypoint.sh;C` — Windows 创建的 ADS（Alternate Data Stream）伪影
+  - `ttyd-session.sh;C` — 同上
+- **影响：** 这些文件可能是 Windows 资源管理器异常操作的产物，不影响 Linux 容器运行。**[风险降低]**：entrypoint.sh 和 ttyd-session.sh 已改为 `COPY --chmod=755` 内置到镜像（4/4 修复），不再通过 bind mount 从 Windows 主机挂载，CRLF 换行符问题的影响已大幅减小。
+- **建议修复：** 删除这些伪影文件，配置 `.gitattributes` 强制 LF 换行。
+
+---
+
+## 攻击路径分析
+
+```
+攻击者
+  │
+  ├── [路径A: Web 终端]
+  │   ├── 1. 扫描发现 7681 端口开放的 ttyd
+  │   ├── 2. 暴力破解弱密码 (默认 jc:1234567，可通过 TTYD_CREDENTIALS 自定义)
+  │   ├── 3. 获得 shell → API 密钥不再在 .bashrc 中（已修复）
+  │   ├── 4. 使用 claude 执行命令（无 allow:["*"] 配置，需交互确认）
+  │   └── 5. privileged 容器 → 完全控制宿主机
+  │
+  ├── [路径B: SSH]
+  │   ├── 1. 扫描发现 2222 端口开放的 SSH
+  │   ├── 2. 暴力破解 root 密码（默认 workpod123，可通过 ROOT_PASSWORD 自定义）
+  │   ├── 3. 直接获得 root shell
+  │   └── 4. privileged 容器 → 完全控制宿主机
+  │
+  └── [路径C: 认证代理]
+      ├── 1. 发现 8080 端口的 auth-proxy
+      ├── 2. 暴力破解 Basic Auth (wk:1234567)
+      ├── 3. 利用 /token 端点的认证旁路
+      ├── 4. 获取 token 后访问 ttyd
+      └── 5. 同路径 A 第 3-5 步
+```
+
+**关键发现：密码已外部化（环境变量注入），entrypoint-test.sh 已归档移除（无 allow:["*"]、无 NOPASSWD sudo、无 .bashrc 密钥写入）。当前主要风险仍为"弱默认密码 + 特权模式"，自定义强密码可显著提升整体安全性。**
+
+---
+
+## 总结与优先级建议
+
+### 立即处理 (P0 — 本周内)
+
+| 编号 | 问题 | 状态 | 原因 |
+|------|------|------|------|
+| S-01 | 硬编码密码 | **[已修复]** / 降级[中危] | 密码已外部化，Dockerfile 默认值仍存 |
+| S-02 | privileged: true | **待处理** | 最高风险的单一配置项 |
+| S-03 | allow: ["*"] + skip-permissions | **[不适用]** | entrypoint-test.sh 已归档 |
+| S-04 | API 密钥暴露 | **[已修复]** | 不再写入 .bashrc |
+
+### 尽快处理 (P1 — 两周内)
+
+| 编号 | 问题 | 状态 | 原因 |
+|------|------|------|------|
+| H-01 | NOPASSWD sudo | **[不适用]** | entrypoint-test.sh 已归档 |
+| H-02 | SSH root 密码登录 | **[部分改进]** | ROOT_PASSWORD 可自定义，默认仍弱 |
+| H-03 | ttyd 弱密码 + 明文传输 | **[已改进]** | TTYD_CREDENTIALS 可配置，默认仍偏弱 |
+| H-05 | auth-proxy.js 安全缺陷 | **待处理** | 认证层可被绕过（已从 _archive 补回主目录） |
+
+### 计划处理 (P2 — 一个月内)
+
+| 编号 | 问题 | 原因 |
+|------|------|------|
+| H-04 | 共享网络隔离 | 横向移动风险 |
+| H-06 | /root 目录挂载 | 敏感文件外露 |
+| M-01 ~ M-06 | 各类中危问题 | 安全加固措施 |
+| L-01 ~ L-05 | 低危问题 | 代码质量和 hygiene |
+
+### 总体评价
+
+WorkPod Alpine 是一个**开发环境工具**，其设计目标（便捷性、开箱即用）与安全性之间存在固有张力。当前配置明显偏向便利性：
+
+**优势：**
+- 采用多阶段构建减小镜像攻击面
+- 使用 Alpine 基础镜像减少包数量
+- 有信号处理和清理机制
+- tmux session 管理支持多用户协作
+
+**核心风险：**
+- **特权模式 + root 运行 + 全权限 AI + 弱密码**的组合构成了"完美风暴"——每个单独看都是常见做法，但叠加在一起使整体安全基线极低
+- 作为开发环境可以接受一定风险，但如果此容器部署在任何可从互联网访问的环境中，应当视为**已被攻陷**
+
+**最低可行安全改进（MVP）：**
+1. 移除 `privileged: true`（除非有明确需求并提供理由）
+2. 密码改为环境变量注入 + 强密码
+3. 移除 `allow: ["*"]` 和 `--dangerously-skip-permissions`
+4. SSH 禁用密码登录或使用强密码
+5. 添加 `.gitignore` 防止敏感文件提交
@@ -0,0 +1,316 @@
+# 架构设计审核报告 -- 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 按需扩展。
@@ -0,0 +1,290 @@
+# Docker 最佳实践审核报告
+
+> 审核对象：WorkPod Alpine 版
+> 审核日期：2026-04-07
+> 审核范围：Dockerfile、docker-compose.yml、entrypoint.sh、ttyd-session.sh、.gitignore、Dockerfile.flux、docker-compose.flux.yml
+
+---
+
+## 镜像分析
+
+| 指标 | Alpine 版 | Ubuntu 版（对照） | 建议 |
+|------|----------|-------------------|------|
+| 大小 | ~436MB | ~2.6GB | Alpine 版体积控制优秀 |
+| 阶段数 | 2（多阶段） | 1（单阶段） | 多阶段构建设计合理 |
+| 基础镜像 | alpine:3.23 (3.4MB) | ubuntu:22.04 (77MB) | Alpine 最小化基础镜像选择正确 |
+| 最终层数 | ~8 层 | ~7 层 | 层数合理 |
+| 包管理器 | apk (--no-cache) | apt (--no-install-recommends) | 两者都做了优化，apk 更彻底 |
+
+---
+
+## 问题清单
+
+### [严重] S1 - 密码硬编码在 Dockerfile 中 **[已修复]**
+
+- **位置：** `Dockerfile:34`
+- **最佳实践：** 密码绝不应写入镜像层，应通过环境变量、Docker secrets 或运行时注入
+- **现状：**
+  ```dockerfile
+  echo "root:${ROOT_PASSWORD:-workpod}" | chpasswd
+  ```
+  ROOT_PASSWORD 已通过环境变量 `${ROOT_PASSWORD}` 注入，不再硬编码在镜像层中。entrypoint.sh 已移除密码明文输出。ttyd 认证也已改用 `${TTYD_CREDENTIALS}` 环境变量（见 M4）。
+- **建议修复：** 已完成。ROOT_PASSWORD 和 TTYD_CREDENTIALS 均通过 docker-compose 环境变量注入。
+
+### [严重] S2 - 以 root 用户运行所有服务
+
+- **位置：** `Dockerfile` 全文、`entrypoint.sh`
+- **最佳实践：** 容器内应以非特权用户运行应用进程
+- **现状：** sshd、ttyd、tmux、Node.js 全部以 root 运行，PermitRootLogin yes
+- **说明：** 当前为开发环境的故意设计。WorkPod 作为全栈开发环境容器，需要 root 权限来安装工具链、管理包、配置系统服务等。生产环境部署时应考虑降权。
+- **建议修复：**
+  - 创建 `developer` 用户运行 ttyd 和开发工具
+  - sshd 可保留 root 但应禁用密码登录，仅允许密钥认证
+  - 添加 `USER` 指令
+
+### [严重] S3 - Compose healthcheck 命令语法错误（管道无法在 CMD 数组中工作） **[已修复]**
+
+- **位置：** `docker-compose.yml:48`
+- **最佳实践：** Compose healthcheck 的 CMD 数组形式中，`|`（管道）不会被 shell 解释
+- **原问题：**
+  ```yaml
+  test: ["CMD", "ss", "-tlnp", "|", "grep", "-qE", ":(22|7681)\\b"]
+  ```
+  这会执行 `ss -tlnp | grep -qE ...` 吗？**不会**。CMD 数组形式是 exec 执行，`|` 被当作 ss 的参数而非管道符。实际效果等同于：
+  ```
+  ss -tlnp "|" grep -qE ":(22|7681)\b"
+  ```
+  这会导致健康检查**始终失败或行为异常**。
+- **对比：** 镜像内 HEALTHCHECK（`Dockerfile:48-49`）使用的是 shell 形式 `CMD netstat ...`，可以正常解析管道。
+- **额外问题：** Alpine 默认不安装 `ss` 命令（属于 iproute2 包，未在 apk add 列表中），即使语法修复也会因命令不存在而失败。
+- **修复状态：** 已改为 CMD-SHELL 形式并使用 netstat：
+  ```yaml
+  test: ["CMD-SHELL", "netstat -tlnp 2>/dev/null | grep -qE ':(22|7681)\\b' || exit 1"]
+  ```
+
+### [高] H1 - privileged: true 过于宽泛 **[部分修复]**
+
+- **位置：** `docker-compose.yml:11`、`docker-compose.flux.yml`
+- **最佳实践：** privileged 应作为最后手段
+- **现状：**
+  - `docker-compose.flux.yml`：已移除 `privileged: true`，改用细粒度 capabilities
+  - `docker-compose.yml`（基础版）：仍保留 `privileged: true`
+- **建议修复：** 基础版 docker-compose.yml 也应同步移除 privileged，统一使用 capabilities 方案。
+
+### [高] H2 - npm 包版本不固定 (@latest)
+
+- **位置：** `Dockerfile:19`
+- **最佳实践：** 所有依赖应固定版本号
+- **现状：**
+  ```dockerfile
+  npm install -g "@z_ai/coding-helper@latest"
+  ```
+  与 Ubuntu 版相同问题。
+- **说明：** 用户决定保持 `@latest`，以便每次构建时自动获取 coding-helper 最新版本。开发环境可接受此策略。
+- **建议修复：** 如需稳定构建可固定版本号（如 `"@z_ai/coding-helper@0.0.7"`），当前保持 @latest 为有意设计。
+
+### [高] H3 - 缺少 .dockerignore 文件 **[已修复]**
+
+- **位置：** 项目根目录
+- **最佳实践：** 排除无关文件以减小构建上下文
+- **原问题：** 没有 `.dockerignore`。以下文件会被发送到 Docker daemon：
+  - `workpod-alpine-latest.tar.gz`（~100MB 导出镜像）
+  - `static/` 目录（前端静态文件）
+  - `auth-proxy.js`, `nginx-map-patch.sh`, `wk.1216.conf`（部署辅助文件）
+  - `.claude/` 配置目录
+  - `ISSUES.md`, `docker-compose-alpine.yml`（文档和备用 compose）
+  - `packages/go1.26.1.linux-amd64.tar.gz`, `packages/rust-*.tar.xz`（未在 Dockerfile 中使用的包）
+- **关键发现：** packages 目录中有 Go 和 Rust 的 tarball，但 Dockerfile 只使用了 node 包。这些大文件（Go ~150MB, Rust ~100MB）每次构建都会被发送到 Docker context。
+- **修复状态：** 已创建 `.dockerignore`，构建上下文缩小至约 275 bytes，排除了所有无关文件和大型包。
+
+### [高] H4 - builder 阶段未清理 npm 缓存和临时文件
+
+- **位置：** `Dockerfile:12-20`
+- **最佳实践：** 多阶段构建的 builder 阶段虽不影响最终镜像大小，但影响构建缓存和构建速度
+- **现状：**
+  ```dockerfile
+  RUN mkdir -p /opt/node \
+      && cd /tmp/packages \
+      && tar -xzf node-v24.14.1-linux-x64-musl.tar.gz -C /opt/node --strip-components=1 \
+      && export PATH="/opt/node/bin:$PATH" \
+      && npm install -g npm@10 \
+      && npm config set registry https://registry.npmmirror.com \
+      && npm install -g "@anthropic-ai/claude-code@2.1.89" \
+      && npm install -g "@z_ai/coding-helper@latest" \
+      && npm cache clean --force
+  ```
+  有 `npm cache clean --force`，但 `/tmp/packages` 目录未被删除（虽然不影响最终镜像，因为 COPY --from=builder 只复制 /opt/node）。
+- **建议修复：** 当前做法可接受。如追求极致可添加 `&& rm -rf /tmp/packages /root/.npm`。
+
+### [中] M1 - COPY 后单独 RUN chmod 而非使用 --chmod **[已修复]**
+
+- **位置：** `Dockerfile:42-44`
+- **最佳实践：** 利用 BuildKit 的 `COPY --chmod` 减少层数
+- **原问题：**
+  ```dockerfile
+  COPY entrypoint.sh /entrypoint.sh
+  COPY ttyd-session.sh /opt/ttyd-session.sh
+  RUN chmod 755 /entrypoint.sh /opt/ttyd-session.sh
+  ```
+  单独一个 RUN chmod 创建了一个额外的镜像层（约几十字节），且与 Ubuntu 版的做法不一致（Ubuntu 版用了 `--chmod=755`）。
+- **修复状态：** 已统一为 `COPY --chmod=755`，移除了多余的 `RUN chmod` 层。
+
+### [中] M2 - 多个 docker-compose 文件缺乏明确分工说明
+
+- **位置：** `docker-compose.yml` / `docker-compose.flux.yml` / `docker-compose-alpine.yml`
+- **最佳实践：** 项目应有唯一的 compose 文件或明确的文件用途区分
+- **现状：** 当前共有 3 个 compose 文件：
+  - `docker-compose.yml`：基础版，带完整配置（healthcheck、资源限制、日志轮转、privileged: true）
+  - `docker-compose.flux.yml`：Flux 版，移除 privileged、使用 capabilities、更精细的配置
+  - `docker-compose-alpine.yml`：精简版（无 healthcheck、无资源限制、无日志配置、不同端口映射）
+- **风险：** 开发者可能混淆该用哪个文件；alpine 备用文件缺配置。
+- **建议修复：**
+  - 在 README 中明确说明各文件用途
+  - 或合并为一个主文件 + 环境覆盖文件
+
+### [中] M3 - openrc 初始化方式不够健壮
+
+- **位置：** `Dockerfile:32`
+- **最佳实践：** Alpine 容器中应谨慎使用 openrc
+- **现状：**
+  ```dockerfile
+  && mkdir -p /run/openrc && touch /run/openrc/softlevel
+  ```
+  这是让 openrc 命令可用的标准做法，但 entrypoint.sh 中并未使用 `service ssh start`（而是直接调用 `/usr/sbin/sshd`），所以 openrc 的初始化可能是多余的。
+- **建议修复：**
+  - 如果不用 openrc 管理 sshd：移除 `openrc` 依赖和 softlevel 初始化，改用 `apk add openssh-server --no-cache`（不带 openrc）
+  - 如果将来要用 openrc：保留当前做法并在注释中说明意图
+
+### [中] M4 - ttyd 认证凭证硬编码 **[已修复]**
+
+- **位置：** `entrypoint.sh:45`
+- **最佳实践：** 认证信息不应硬编码
+- **原问题：**
+  ```bash
+  ttyd -W -c ada:123 -t fontSize=16 ...
+  ```
+  用户名 `ada` 密码 `123` 写死在脚本中。虽然比 Ubuntu 版的无认证好，但仍然是弱凭证+硬编码。
+- **修复状态：** 已改用 `${TTYD_CREDENTIALS}` 环境变量注入，entrypoint 中动态拼接 `-c` 参数。默认值保留为兼容性兜底。
+
+### [中] M5 - 资源限制可能偏低 **[已修复]**
+
+- **位置：** `docker-compose.yml:42-44`
+- **最佳实践：** 资源限制应根据实际负载设置
+- **原问题：**
+  ```yaml
+  limits:
+    memory: 4G
+  reservations:
+    memory: 512M
+  ```
+  Alpine 版虽然基础镜像小，但如果用户安装 Rust/Go/Python 工具链并编译大型项目，512M 保留内存可能不足导致 OOM Kill。
+- **修复状态：** reservation 已从 512M 提升到 1G，更适合 Claude Code 等高内存占用工具的运行。
+
+### [低] L1 - 缺少 LABEL 元数据 **[已修复]**
+
+- **位置：** `Dockerfile`
+- **最佳实践：** 镜像应包含维护者、版本等标签
+- **原问题：** 无任何 LABEL 指令。
+- **修复状态：** 已添加 maintainer + Open Containers 标准标签（org.opencontainers.image.*）。
+
+### [低] L2 - 基础镜像未指定 digest
+
+- **位置：** `Dockerfile:4`, `Dockerfile:23`
+- **最佳实践：** 生产级镜像应 pin 到具体 digest
+- **现状：** 两处 `FROM alpine:3.23` 均未锁定 digest。
+- **建议修复：** 开发环境可接受，CI/CD 环境建议锁定。
+
+### [低] L3 - HEALTHCHECK 使用 netstat 而非 ss
+
+- **位置：** `Dockerfile:48-49`
+- **最佳实践：** 优先使用更现代的工具
+- **现状：**
+  ```dockerfile
+  CMD netstat -tlnp 2>/dev/null | grep -qE ':(22|7681)\b' || exit 1
+  ```
+  netstat 已被标记为 deprecated，Alpine 的 busybox 提供 netstat 但功能有限。`netstat -p`（显示 PID/程序名）在 busybox 版本中可能不支持。
+- **验证：** Alpine 的 busybox netstat 不支持 `-p` 参数，因此 `netstat -tlnp` 中的 `-p` 会被忽略，但仍能检查端口是否存在。
+- **建议修复：** 当前可用但不够精确。如需进程级检查，需安装 `iproute2-ss`（提供 ss）或 `net-tools`（提供完整 netstat）。当前做法作为端口可达性检查足够。
+
+### [低] L4 - entrypoint.sh 中 PATH 注入写到 /etc/profile.d/
+
+- **位置：** `entrypoint.sh:32-40`
+- **最佳实践：** 容器内动态修改系统配置目录应注意幂等性
+- **现状：** 每次启动都会覆写 `/etc/profile.d/dev-tools.sh`，如果文件内容需要更新则没问题，但写入操作本身在容器中是不必要的（因为每次启动都是全新状态，除非挂载了持久化 root 目录）。
+- **建议修复：** 当前后果无害。如果 data/home/root 被挂载为持久化，这个设计是有意义的（让 SSH 登录也能获得正确的 PATH）。保持现状即可。
+
+### [低] L5 - docker-compose-alpine.yml 缺少关键配置
+
+- **位置：** `docker-compose-alpine.yml`
+- **最佳实践：** 所有 compose 文件应包含最低限度的运维配置
+- **现状：** 该文件缺少：
+  - healthcheck（服务不可观测）
+  - logging 配置（日志无限增长风险）
+  - resource limits（无资源隔离）
+  - restart 策略（有 `restart: unless-stopped`，此项 OK）
+- **建议修复：** 标注此文件为"快速启动/测试专用"，或补齐缺失配置。
+
+---
+
+## 与 Ubuntu 版的关键差异分析
+
+| 对比维度 | Ubuntu 版 | Alpine 版 | 评价 |
+|---------|----------|----------|------|
+| 构建策略 | 单阶段 | 多阶段 | Alpine 更优 |
+| 镜像体积 | ~2.6GB | ~436MB | Alpine 优势明显（6倍差距） |
+| ttyd 认证 | 无（`-W`） | 有（`-c ada:123`） | Alpine 更安全（尽管凭证弱） |
+| 健康检查命令 | `ss -tlnp`（镜像）/ `netstat`（compose） | `netstat`（镜像）/ `ss`（compose，**语法错误**） | Ubuntu compose 覆盖合理；Alpine compose 有 bug |
+| COPY --chmod | 使用 | **已使用**（统一为 `COPY --chmod=755`） | 两者一致 |
+| 密码输出 | 明文打印 | 明文打印 | 两者都有问题 |
+| 开发工具支持 | Node.js only | Node.js + Rust + Go + Python 自动检测 | Alpine 功能更丰富 |
+| extra compose 文件 | 无 | 有（docker-compose-alpine.yml） | 增加维护复杂度 |
+
+---
+
+## 优化建议汇总（按收益排序）
+
+| 排名 | 建议 | 严重度 | 状态 | 实施难度 |
+|------|------|--------|------|---------|
+| 1 | **修复 Compose healthcheck 语法错误**（CMD -> CMD-SHELL，ss -> netstat） | 严重 | **[已修复]** | 低（改一行） |
+| 2 | 创建 `.dockerignore`（排除 Go/Rust 包 ~250MB + 其他无用文件） | 高 | **[已修复]** | 低（5分钟） |
+| 3 | 密码外部化（SSH + ttyd 双重硬编码） | 严重 | **[已修复]** | 中（改 compose + entrypoint） |
+| 4 | 固定 coding-helper 版本 @latest -> 具体版本 | 高 | 保持 @latest（有意设计） | 低（改一行） |
+| 5 | COPY 统一使用 --chmod（消除多余 RUN 层） | 中 | **[已修复]** | 低（改几行） |
+| 6 | 明确多个 compose 文件的定位（当前 3 个：yml / .flux.yml / -alpine.yml） | 中 | 待改进 | 低（加注释或重构） |
+| 7 | 移除不必要的 openrc 依赖（减小攻击面） | 中 | 待处理 | 低（删几行） |
+| 8 | 提升 memory reservation 到 1G+ | 中 | **[已修复]** | 低（改数字） |
+| 9 | 添加 LABEL 元数据 | 低 | **[已修复]** | 低（加几行） |
+| 10 | privileged 降级为 capabilities（flux 版已完成，基础版待同步） | 高 | **[部分修复]** | 高（需测试兼容性） |
+
+---
+
+## 总体评价
+
+| 维度 | 评分 | 说明 |
+|------|------|------|
+| 镜像优化 | A- | 多阶段构建、体积控制优秀、apk --no-cache、.dockerignore 已就位 |
+| 编写规范 | A- | COPY --chmod 统一、LABEL 完整、结构清晰 |
+| Compose 配置 | B | healthcheck 已修复、3 个 compose 文件需明确分工、flux 版已移除 privileged |
+| 安全性 | C | 密码已外部化、ttyd 凭证环境变量化、root 运行为开发有意设计、privileged 部分修复 |
+| 运维友好度 | A- | 信号处理完善、开发工具自动检测、启动信息详细、labels 完整、reservation 提升至 1G |
+
+**综合评级：B+**
+
+Alpine 版在镜像构建方面表现优秀（多阶段、体积小、apk 高效、.dockerignore）。上一轮审核中的关键功能性 bug（healthcheck 语法错误）和严重安全问题（密码硬编码）均已修复。安全性从 D+ 提升到 C，主要得益于密码/凭证外部化和 healthcheck 修复。剩余待改进项：基础版 docker-compose.yml 的 privileged 移除、多 compose 文件策略统一、openrc 依赖清理。
+
+### 最高优先级修复项
+
+**已完成：**
+- ~~`docker-compose.yml:48`~~ — healthcheck 命令已改为 CMD-SHELL + netstat **[已修复]**
+- ~~密码和 ttyd 凭证~~ — 已通过环境变量注入 **[已修复]**
+- ~~`.dockerignore`~~ — 已创建，构建上下文 ~275 bytes **[已修复]**
+- ~~COPY --chmod~~ — 已统一使用 **[已修复]**
+- ~~LABEL 元数据~~ — 已添加 maintainer + OC labels **[已修复]**
+- ~~memory reservation~~ — 已提升至 1G **[已修复]**
+- ~~privileged 降级~~ — flux 版已完成，基础版待同步 **[部分修复]**
+
+**待处理：**
+- 基础版 `docker-compose.yml` 移除 `privileged: true`，同步 flux 版的 capabilities 方案
+- 明确 3 个 compose 文件的分工定位（README 或文件内注释）
+- openrc 依赖评估与清理（如不使用 service 命令可移除）
+- `@z_ai/coding-helper@latest` 版本固定（当前保持 @latest 为有意设计）
@@ -0,0 +1,204 @@
+# Shell 脚本质量审核报告
+
+> 审核日期：2026-04-07
+> 审核范围：WorkPod Alpine（含 Test 变体）全部 Shell 脚本
+> 审核人：Shell 脚本专家
+
+---
+
+## 脚本清单
+
+| 脚本 | 行数 | 用途 | 复杂度 |
+|------|------|------|--------|
+| entrypoint.sh | 81 | Alpine 版容器入口，启动 SSH + ttyd + 开发工具检测 | 中 |
+| entrypoint-test.sh | 129 | Test 容器入口，额外创建 developer 用户 + Claude 全权限配置 | 中高 | 已归档(_archive/)，非当前活跃 |
+| ttyd-session.sh | 63 | tmux 会话管理，URL 参数解析 + 交互式菜单 | 中 |
+| **合计** | **273** | | |
+
+---
+
+## 逐脚本审核
+
+### entrypoint.sh（Alpine 版）
+
+**文件路径：** `E:/wk-lab/workpod/entrypoint.sh`
+
+#### 健壮性
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| R1 | **SSHD_PID 未赋值（与 Ubuntu 版相同的问题）** | 高 | `cleanup()` 中 `kill "$SSHD_PID"` 因 PID 始终为 0 而跳过。`/usr/sbin/sshd` 在第42行前台启动（无 `&`），实际上 sshd 作为守护进程运行后返回，但未捕获其 PID。应改为 `/usr/sbin/sshd & SSHD_PID=$!` 或在 cleanup 中用 `pkill sshd`。 |
+| R2 | **sshd 未使用 `-D` 前台模式** | 中 | 第42行直接调用 `/usr/sbin/sshd`，它会 fork 为守护进程。如果后续命令失败导致脚本退出，sshd 会成为孤儿进程。建议用 `-D` 参数保持前台或正确追踪 PID。 |
+| R3 | **sleep 1 硬编码等待时间** | 低 | 与 Ubuntu 版相同，仅等待 1 秒判断 ttyd 存活。慢速系统上可能不够。 |
+| R4 | **dev-tools.sh 中的 ls -d 可能匹配多个目录** | 低 | 第38行 `ls -d /root/rust-*/bin` 如果存在多个 rust 版本目录，`head -1` 只取第一个。行为可预测但隐式依赖排序。 |
+| R5 | **cleanup 中 wait 无参数** | 低 | 第11行 `wait 2>/dev/null` 等待所有后台子进程。由于只跟踪了 TTYD_PID 和 SSHD_PID（后者实际为 0），行为基本正确但语义不精确。 |
+
+#### 可移植性
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| P1 | **shebang 使用 bash 但环境为 Alpine/musl** | 中 | `#!/bin/bash` 要求安装 `bash` 包。Dockerfile 第31行已包含 `bash` 依赖，所以当前可工作。但如果未来精简镜像可能出问题。脚本中未使用任何 bashism（数组、`[[ ]]` 等），理论上可改用 `#!/bin/sh`。 |
+| P2 | **pidof 替代 pgrep** | 正面 | 第55行使用 `pidof sshd` 而非 `pgrep -x sshd`，这是正确的 POSIX 兼容选择，在 BusyBox 环境下可靠工作。 |
+| P3 | **gvm source 命令** | 低 | dev-tools.sh 第34行 `source /root/gvm/scripts/gvm` 依赖 gvm 的初始化脚本格式。如果 gvm 不存在该路径会静默失败（有 `2>/dev/null`）。 |
+
+#### 安全性
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| S1 | **ttyd 密码过于简单 `ada:123`** | **[已改进]** | 原第45行 `-c ada:123` 已改为从 `${TTYD_CREDENTIALS:-jc:1234567}` 环境变量读取，不再硬编码在脚本中。密码强度可通过环境变量灵活配置。 |
+| S2 | **硬编码密码明文出现在脚本和日志中** | **[已改进]** | 同上，密码已改为通过环境变量 `TTYD_CREDENTIALS` 传入，不再明文出现在脚本源码中。 |
+| S3 | **dev-tools.sh 使用单引号 heredoc（安全）** | 正面 | 第32行 `<< 'PROFILE'` 阻止变量展开，防止注入。这是正确的做法。 |
+| S4 | **无用户隔离** | 信息 | Alpine 默认版直接以 root 运行一切，没有像 Test 版那样创建 developer 用户。作为开发环境可接受。 |
+
+#### 代码质量
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| Q1 | **开发工具检测逻辑完善** | 正面 | 覆盖 cargo/rustup/gvm/pyenv/go/rust独立安装/local bin 共 7 种开发工具路径。 |
+| Q2 | **双轨 PATH 设置** | 正面 | 既在当前 shell 设置 export（第19-29行），又写入 /etc/profile.d/dev-tools.sh（第32-40行）确保新会话生效。设计合理。 |
+| Q3 | **启动信息展示完整** | 正面 | 展示 Node/npm/Claude/Rust/Go/Python 版本 + 连接方式，便于快速确认环境状态。 |
+| Q4 | **版本检测容错好** | 正面 | 所有 `--version` 命令都有 `2>/dev/null \|\| echo '未安装'` 保护。 |
+| Q5 | **cleanup 函数与 Ubuntu 版完全重复** | 低 | cleanup/trap 模式在三份 entrypoint 中复制粘贴。 |
+
+#### 代码质量评分：**7.5 / 10**
+
+> 扣分项：SSHD_PID 未赋值（-1）、密码过弱（-0.5）、sshd 前台模式（-0.5）、代码重复（-0.5）
+
+---
+
+### entrypoint-test.sh（Test 容器入口） **[归档]**
+
+> 此文件已移至 `_archive/`，以下问题仅作历史记录。
+
+**文件路径：** `E:/wk-lab/workpod-alpine/entrypoint-test.sh`（已归档至 `_archive/`）
+
+#### 健壮性
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| R1 | **SSHD_PID 未赋值（继承自 Alpine 版）** | 高 | 同 entrypoint.sh 的 R1 问题。 |
+| R2 | **adduser -D 无密码设置** | 中 | 第32行 `adduser -D -s /bin/bash developer` 创建用户时未设置密码。developer 用户只能通过 sudo 操作，不能直接 SSH 登录（除非配置了密钥认证）。这可能是故意的，但应明确注释说明。 |
+| R3 | **sudoers 文件写入无原子性保护** | 低 | 第34行直接 `echo ... > /etc/sudoers.d/developer`。如果脚本在中途被中断，可能留下不完整的 sudoers 文件导致 sudo 不可用。建议先写临时文件再 mv。 |
+| R4 | **chown -R 递归操作范围大** | 低 | 第37行 `chown -R developer:developer /home/developer` 对整个 home 目录递归修改所有权。如果有其他进程正在向该目录写入文件，可能出现竞态。但在容器启动阶段风险极低。 |
+| R5 | **settings.json 双引号 heredoc 安全** | 正面 | 第41行和第51行都使用 `<< 'SETTINGS'` 单引号 heredoc，JSON 内容不会被 shell 解释。做法正确。 |
+
+#### 可移植性
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| P1 | **adduser -D 是 Alpine 特有** | 信息 | `-D` 标志表示"不分配密码"，是 BusyBox adduser 的扩展。本脚本专用于 Alpine，无移植需求。 |
+| P2 | **bash 依赖同 Alpine 版** | 中 | 同 entrypoint.sh 的 P1 问题。 |
+
+#### 安全性
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| S1 | **Claude Code settings.json 全权限 allow:["*"]** | **严重 [归档]** | 第43-47行和第53-57行为 root 和 developer 用户都设置了 `"allow": ["*"]`，意味着 Claude Code 可以执行任意文件读写、命令执行等操作而无需用户确认。虽然这是开发环境的故意设计（沙箱用途），但应在文档中明确标注此安全策略的影响范围。**归档文件中的配置，不影响当前版本。** |
+| S2 | **.bashrc 中环境变量传递方式** | 中 | 第67-70行使用双引号 heredoc `<< BASHRC` 并在其中引用 `${ANTHROPIC_AUTH_TOKEN}` 等变量。这里变量会在 heredoc 写入时展开——即使用 entrypoint 进程的环境变量值。这意味着：(1) 如果环境变量未设置，会写入空字符串；(2) 如果值包含特殊字符（如 `$`` `），可能被二次解释。当前用法基本安全但需注意边界情况。 |
+| S3 | **NOPASSWD:ALL sudo 权限** | 高 [归档] | 第34行给 developer 用户无密码完整 sudo 权限。配合 Claude Code 全权限配置，developer 用户等同于 root。这是有意的设计决策（全权限沙箱），但安全边界完全消失。**同上，归档文件中的配置。** |
+| S4 | **.bashrc 中 PATH 包含 `$PATH`** | 正面 | 第66行 `export PATH="/usr/local/bin:/usr/bin:/bin:\$PATH"` 使用 `\$PATH` 在双引号 heredoc 中转义 `$`，确保写入文件的是字面量 `$PATH` 而非展开后的值。这个转义是正确的。 |
+
+#### 代码质量
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| Q1 | **功能模块划分清晰** | 正面 | 按顺序分为：开发工具检测 -> 用户创建 -> Claude 配置(root) -> Claude 配置(developer) -> 别名配置(root) -> 启动服务 -> 信息展示。结构清晰。 |
+| Q2 | **root 和 developer 配置对称处理** | 正面 | settings.json 和 .bashrc 分别为两个用户配置，且 chown 所有权正确。 |
+| Q3 | **alias 区分 root/developer 参数** | 正面 | root 用 `--allow-dangerously-skip-permissions`（第76行），developer 用 `--dangerously-skip-permissions`（第65行）。准确反映了 Claude Code 对 root 用户的限制。 |
+| Q4 | **与 entrypoint.sh (Alpine) 大量重复** | 高 [归档] | 开发工具检测（第19-29行 vs 第19-29行完全相同）、dev-tools.sh 写入（第80-88行 vs 第32-40行完全相同）、cleanup 函数（第7-14行相同）、服务启动和检查（第90-106行几乎相同）。唯一差异是用户创建和 Claude 配置部分（第31-78行）。重复率约 65%。**因归档而不再是活跃问题。** |
+| Q5 | **环境变量默认值处理良好** | 正面 | 第69-70行 `${API_TIMEOUT_MS:-3000000}` 和 `${CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC:-1}` 提供了合理的默认值。 |
+| Q6 | **端口/标题/密码硬编码** | 低 | 7682、2223、"WorkPod Test"、`jc:1234567` 全部硬编码。（注：此为已归档的 entrypoint-test.sh 中的历史值；当前基础实例已使用 2222/7681 端口，凭据通过环境变量注入） |
+
+#### 代码质量评分：**7 / 10** （历史评分，文件已归档）
+
+> 扣分项：与 entrypoint.sh 高度重复（-1.5）、SSHD_PID 未赋值（-1）、全权限安全策略未文档化（-0.5）
+
+---
+
+### ttyd-session.sh（tmux 会话管理）
+
+**文件路径：** `E:/wk-lab/workpod/ttyd-session.sh`
+
+#### 健壮性
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| R1 | **set -e 缺失** | 中 | 脚本没有 `set -e`。如果中间某条命令失败（如 `tmux list-sessions`），脚本会继续执行可能导致错误状态扩散。考虑到脚本的交互性质（需要 read 输入），`set -euo pipefail` 更合适但需注意 `read` 在 set -e 下的行为（read 到 EOF 返回非零不会终止脚本，因为它是条件上下文的一部分）。 |
+| R2 | **SESSION_NAME 初始为空字符串** | 低 | 第4行 `SESSION_NAME=""` 初始化为空。如果 TTYD_QUERY_STRING 解析也得到空值（第9行的 grep 无匹配），则进入交互菜单分支。流程正确但变量生命周期不够明确。 |
+| R3 | **tmux session 名过滤后可能为空** | 中 | 第55行 `tr -cd 'a-zA-Z0-9_\-'` 过滤后如果 SESSION_NAME 变成空字符串（例如原始输入全是特殊字符），第58行 `tmux new-session -t ""` 会创建一个名为空字符串的 session。虽然 tmux 允许这样做但不推荐。应在过滤后检查是否为空并赋予默认值 "default"。 |
+| R4 | **sed -n "${CHOICE}p" 未做范围校验** | 中 | 第45行 `sed -n "${CHOICE}p"` 直接将用户输入的数字传给 sed。虽然前面有 `grep -qE '^[0-9]+$'` 校验了纯数字，但没有检查数字是否在有效范围内（1 到 session 数量之间）。超出范围的 CHOICE 会导致 sed 输出空行，SESSION_NAME 被设为空字符串，然后触发 R3 的问题。 |
+| R5 | **EXISTING 变量的 word splitting** | 低 | 第20行 `tmux list-sessions` 输出类似 `my_session: (attached)` 格式，awk 提取第一列后得到 `my_session:`（带冒号）。第24行 `for s in $EXISTING` 依赖 word splitting 来遍历 session 名。如果 session 名包含空格（虽然 tmux 不允许），会出错。实际风险低。 |
+| R6 | **exec tmux attach/new 替换进程** | 正面 | 第59-61行使用 `exec` 替换当前 shell 进程为 tmux，避免多余的 shell 进程残留。这是正确的做法。 |
+
+#### 可移植性
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| P1 | **BusyBox awk 兼容性（已修复）** | 已解决 | 历史上使用 `grep -oP`（Perl 正则）解析 query string，在 BusyBox 中不可用。当前版本第9行改用 `tr '\&' '\n' \| grep '^session=' \| cut -d= -f2` 的管道链，完全兼容 BusyBox。 |
+| P2 | **tr -cd 字符类兼容性** | 低 | 第55行 `tr -cd 'a-zA-Z0-9_\-'` 中的 `\-` 在 GNU tr 和 BusyBox tr 中都能正确解释为字面量连字符。POSIX 标准中字符类内的 `-` 放在首位或末位或转义均可。 |
+| P3 | **printf 格式化** | 正面 | 第25行 `printf "║ [%d] %-33s║\n" "$I" "$s"` 使用标准 printf 格式，跨实现兼容。 |
+| P4 | **clear 命令** | 信息 | 第51行 `clear` 依赖 terminfo 数据库。在 Docker 的 ttyd 环境中通常可用。 |
+| P5 | **grep -qE** | 正面 | 第44行使用 `grep -qE`（扩展正则），BusyBox awk 支持此选项。 |
+
+#### 安全性
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| S1 | **TTYD_QUERY_STRING 注入防护** | 正面 | 第9行通过管道链 `tr \| grep \| cut` 解析，最终结果经过第55行 `tr -cd` 过滤为安全字符集。即使攻击者构造恶意的 query string（如 `session=;rm -rf /`），也会被过滤掉。安全性良好。 |
+| S2 | **用户输入 SESSION_NAME 注入防护** | 正面 | 第55行将用户交互输入同样通过 `tr -cd` 过滤，tmux session 名被限制在 `[a-zA-Z0-9_-]` 字符集中。无法注入 shell 命令。 |
+| S3 | **无外部命令拼接** | 正面 | 所有变量传递给 tmux 时都加了双引号（`"$SESSION_NAME"`），防止 word splitting 和 globbing。 |
+
+#### 代码质量
+
+| # | 问题 | 严重度 | 说明 |
+|---|------|--------|------|
+| Q1 | **UI 设计精美** | 正面 | 使用 Unicode 制表符绘制边框，视觉效果专业。编号选择 + 自定义名称的双重输入方式用户体验好。 |
+| Q2 | **双模式设计合理** | 正面 | URL 带 `?session=xxx` 直接进入（自动化场景），不带参数显示菜单（手动场景）。覆盖了两种主要使用方式。 |
+| Q3 | **默认值 fallback** | 正面 | 第39-41行用户输入空时默认为 "default"。 |
+| Q4 | **缺少 set -e/o pipefail** | 低 | 如 R1 所述。对于这种交互式脚本，建议至少加 `set -uo pipefail`（不含 -e 以免影响 read）。 |
+| Q5 | **冒号未从 session 名中去除** | 低 | 第20行 awk `{print $1}` 提取的是 `session_name:`（带尾部冒号）。这个带冒号的名字会被用于显示（第25行）和选择（第45行 sed 取行），最终传入 tmux 的也是带冒号的名字。tmux 本身允许 session 名包含冒号，所以功能不受影响，但显示上不够干净。可以用 `tr -d ':'` 清理。 |
+| Q6 | **代码简洁高效** | 正面 | 仅 63 行实现了 query string 解析、交互式菜单、session 创建/附加的完整功能。没有冗余逻辑。 |
+
+#### 代码质量评分：**8 / 10**
+
+> 扣分项：缺少 set -euo pipefail（-0.5）、session 名空值/超范围未防护（-1）、冒号未清理（-0.5）
+
+---
+
+## 跨脚本问题
+
+| # | 问题 | 影响范围 | 说明 |
+|---|----------|----------|------|
+| X1 | **entrypoint.sh 与 entrypoint-test.sh(归档) 高度重复** | 2 个文件（其中1个已归档） | 开发工具检测(12行)、dev-tools.sh 写入(8行)、cleanup函数(8行)、trap注册(1行)、SSH启动+检查(10行)、ttyd启动+检查(8行)、信息展示(18行)、exec sleep(1行) —— 约 66 行完全相同，占总代码量 66/210 = 31%（不计公共部分则重复率更高）。**优先级大幅降低（entrypoint-test.sh 已归档）。** |
+| X2 | **三个版本的 cleanup 函数逐字相同** | 3 个文件 | Ubuntu/Alpine/Test 三份 entrypoint 的 cleanup 函数（第7-14行）完全一致。这是典型的 DRY 违反。 |
+| X3 | **ttyd 认证密码三套不同策略** | 3 个文件 | Ubuntu版无密码 / Alpine版 `ada:123` / Test版 `jc:1234567`。安全级别不一致，容易在部署时混淆。**[已修复]** — 当前版本统一从 `${TTYD_CREDENTIALS}` 环境变量读取。 |
+| X4 | **dev-tools.sh 内容在 Alpine 和 Test 版中逐字相同** | 2 个文件 | entrypoint.sh 第80-88行与 entrypoint-test.sh 第32-40行的 heredoc 内容完全一致。 |
+| X5 | **SSHD_PID 跟踪在所有版本中都无效** | 3 个文件（其中1个已归档） | 三个版本的 entrypoint 都声明了 `SSHD_PID=0` 且从未赋值，cleanup 中的 `kill "$SSHD_PID"` 分支永远不会执行。这是一个系统性缺陷。（低优先级，未修复） |
+| X6 | **端口号/标题/密码散落在各脚本中** | 3 个文件（其中1个已归档） | 修改端口或密码需要在多个文件中同步修改，遗漏任一文件会导致配置不一致。**[已改善]** — 当前版本已集中到 docker-compose.yml 的 environment 配置中管理。 |
+
+---
+
+## Top 10 改进建议
+
+| 优先级 | 建议 | 涉及脚本 | 收益 |
+|--------|-------|----------|------|
+| P0 | **重构 entrypoint 公共框架（配置驱动）** | entrypoint.sh (x2, 其中1个已归档) | 消除 ~66 行重复代码，新增容器变体只需配置文件（优先级降低：entrypoint-test.sh 已归档） |
+| P1 | **修复 SSHD_PID 追踪（统一方案）** | entrypoint.sh (x3) | 实现 sshd 优雅关闭，防止孤儿进程 |
+| P2 | **ttyd-session.sh 添加 set -uo pipefail + 输入校验** | ttyd-session.sh | 防止空 session 名和越界访问 |
+| P3 | **统一 ttyd 认证策略，密码从环境变量读取** | entrypoint.sh (x3) | 消除安全配置不一致，支持灵活部署（**已完成**） |
+| P4 | **ttyd-session.sh 清理 session 名尾部冒号** | ttyd-session.sh | UI 显示更干净，避免意外行为 |
+| P5 | **entrypoint-test.sh sudoers 文件写入增加原子性** | entrypoint-test.sh | 防止中断导致 sudo 不可用 |
+| P6 | **document 全权限安全策略的影响范围** | entrypoint-test.sh | 让使用者明确了解 `allow:["*"]` + `NOPASSWD:ALL` 的安全含义 |
+| P7 | **端口/标题/密码等配置外部化为环境变量** | entrypoint.sh (x3) | docker-compose.yml 集中管理，消除散落配置 |
+| P8 | **考虑 entrypoint.sh shebang 改为 /bin/sh** | entrypoint.sh (Alpine x2) | 减少 bash 依赖，Alpine 环境更轻量（需确认无 bashism） |
+| P9 | **sshd 启动增加 -D 模式或 PID 文件追踪** | entrypoint.sh (Alpine x2) | 更精确的进程生命周期管理 |
+
+---
+
+## 附录：历史 Bug 回顾
+
+| Bug | 影响 | 当前状态 |
+|-----|------|----------|
+| grep -P 在 BusyBox 不可用 | Alpine 环境 TTYD_QUERY_STRING 解析失败 | ttyd-session.sh 第9行已改用 `tr & '\n' \| grep '^session=' \| cut -d= -f2` 管道链，完全兼容 BusyBox |
+| heredoc 单引号阻止变量展开 | .bashrc 中 ANTHROPIC_AUTH_TOKEN 等环境变量无法传递到 developer 用户 | entrypoint-test.sh 第64行已改用 `<< BASHRC` 双引号 heredoc，变量在写入时正确展开；`\$PATH` 转义确保字面量输出 |
+| dev-tools.sh 反斜杠转义问题 | profile.d 脚本中 `\$PATH` 或 `\\` 导致语法错误 | 当前版本 dev-tools.sh 使用单引号 heredoc `<< 'PROFILE'`，内容原样写入无需转义，已修复 |
@@ -0,0 +1,333 @@
+# 性能与可维护性审核报告
+
+> 审核日期：2026-04-07
+> 审核范围：WorkPod Alpine 版 (E:/wk-lab/workpod)
+> 镜像大小：~436MB | 基础镜像：alpine:3.23（多阶段构建）| 内存限制：4G / 1G reservation
+> 部署环境：测试服 4 个实例共享镜像
+
+---
+
+## 一、性能审核
+
+### 1.1 镜像性能
+
+| 指标 | 当前值 | 行业标准（同类开发容器） | 评价 |
+|------|--------|------------------------|------|
+| **镜像大小** | ~436 MB | 200~500 MB 为佳 | **优** -- 多阶段构建效果显著 |
+| **基础镜像** | alpine:3.23 (~7MB) | alpine/debian-slim | **优** -- 最小化基础 |
+| **构建层数** | 5 层有效（2阶段） | 3~6 层为佳 | **优** -- 多阶段构建，builder 层不进入最终镜像 |
+| **层缓存命中率** | 中等 | >70% 为佳 | 中 -- npm install 每次可能因版本变化失效 |
+| **构建产物清理** | builder 阶段自动丢弃 | 必须清理 | **优** -- 多阶段天然隔离 |
+| **推送/拉取效率** | 436 MB 全量传输 | <500 MB 理想 | **优** -- 比 Ubuntu 版小 6 倍 |
+| **存储占用** | ~436 MB/实例 x 4 = ~1.7 GB | <2 GB 总量 | **优** -- 4 实例总占用仍小于 Ubuntu 单实例 |
+
+#### 层分析（多阶段构建）
+
+```
+========== Builder 阶段 (不进入最终镜像) ==========
+Layer B1 (FROM):       alpine:3.23                  ~7 MB
+Layer B2 (RUN apk):    xz + libstdc++               ~15 MB
+Layer B3 (COPY pkgs):  本地 packages/                ~325 MB
+Layer B4 (RUN npm):    Node.js + claude + helper     ~400 MB (含缓存)
+─────────────────────────────────────────────────────
+Builder 阶段总计:      ~747 MB (构建时临时)
+
+========== 运行阶段 (最终镜像) ==========
+Layer R1 (FROM):       alpine:3.23                  ~7 MB
+Layer R2 (RUN apk):    curl/git/ssh/ttyd/tmux/bash   ~80 MB
+Layer R3 (COPY):       /opt/node -> /usr/local      ~200 MB (仅产物)
+Layer R4 (COPY+RUN):   entrypoint + ttyd-session     <10 KB
+─────────────────────────────────────────────────────
+最终镜像总计:          ~436 MB (压缩后)
+```
+
+#### 与 Ubuntu 版对比
+
+| 对比项 | Ubuntu 版 | Alpine 版 | 倍率 |
+|--------|----------|-----------|------|
+| 镜像大小 | 2.6 GB | 436 MB | **6x 更小** |
+| 基础镜像 | ubuntu:22.04 (77MB) | alpine:3.23 (7MB) | **11x 更小** |
+| 内存基线 | ~400 MB | ~80 MB | **5x 更省** |
+| 构建策略 | 单阶段 | 多阶段 | Alpine 更优 |
+| 推送时间(100Mbps) | ~3.5 min | ~35 s | **6x 更快** |
+
+### 1.2 运行时性能
+
+| 指标 | 当前值 | 行业标准 | 评价 |
+|------|--------|---------|------|
+| **内存基线占用** | ~80-120 MB (Alpine base) | 50-150 MB | **优** -- Alpine 最小化系统 |
+| **应用内存** | Node.js ~50 MB + ttyd ~8 MB + sshd ~3 MB + tmux ~2 MB | 合理范围 | **优** |
+| **总内存限制** | 4G limit / 1G reservation | 开发容器 2-4G 即够 | **良** -- reservation 1G 合理 |
+| **启动时间** | ~3-5s (entrypoint 执行) | <10s 可接受 | **良** |
+| **entrypoint 流程** | PATH检测 -> 用户创建 -> 配置写入 -> SSH启动 -> ttyd启动 -> 健康检查 | 较复杂 | 中 -- 步骤较多但必要 |
+| **信号处理** | trap SIGTERM/SIGINT/SIGQUIT + cleanup() | 必须具备 | 良 -- 有优雅关闭 |
+| **ttyd 性能** | WebSocket 直连 + tmux 会话管理 | 标准 | **优** -- 会话恢复能力强 |
+| **特权模式** | privileged: true | 应避免 | 差 -- 安全风险 |
+| **4 实例并发** | 共享同一镜像 | 标准 | **优** -- 镜像小，存储压力低 |
+
+#### 启动流程时间分解
+
+```
+t=0s    entrypoint.sh 开始执行
+t≈0.05s PATH 自动检测 (6 个目录检查)
+t≈0.1s  创建 developer 用户 + sudoers + .claude 配置 (~10 个文件操作)
+t≈0.3s  写入 /etc/profile.d/dev-tools.sh
+t≈0.5s  /usr/sbin/sshd 启动
+t≈0.6s  ttyd -W -c ... /opt/ttyd-session.sh & (后台启动)
+t≈1.6s  sleep 1 (等待 ttyd 就绪)
+t≈1.7s  kill -0 $TTYD_PID (健康验证)
+t≈1.8s  pidof sshd (SSH 验证)
+t≈2.5s  版本检测输出 (node/npm/claude/rust/go/python)
+t≈2.5s  exec sleep infinity (PID 1 接管)
+总计：约 2.5-4 秒（比 Ubuntu 稍慢，因多了用户创建和配置步骤）
+```
+
+### 1.3 I/O 性能
+
+| 指标 | 当前配置 | 评价 |
+|------|---------|------|
+| **卷挂载方式** | bind mount (`./data/workspace:/workspace`) | 标准 |
+| **日志驱动** | json-file, max-size=10m, max-file=3 | 良 -- 有轮转 |
+| **/root 持久化** | docker-compose-alpine.yml 有挂载 (`./data/workpod-alpine/root:/root`) | 良 -- 支持工具持久化 |
+| **tmpfs 使用** | 未使用 | 中 -- /tmp、/run 可用 tmpfs 提升性能 |
+| **entrypoint.sh / ttyd-session.sh 内置** | `COPY --chmod=755 entrypoint.sh /entrypoint.sh` + `COPY --chmod=755 ttyd-session.sh /opt/ttyd-session.sh` (Dockerfile) | **优** -- 已内置到镜像，符合 immutable artifact 最佳实践 |
+
+#### entrypoint / ttyd-session 内置到镜像
+
+entrypoint.sh 和 ttyd-session.sh 均已通过 `COPY --chmod=755` 固化到镜像中（Dockerfile），不再使用 bind mount 外挂。这是 4/4 修复 execvp failed 问题时做的改动。
+
+**改进效果**：
+- 消除了宿主机文件缺失导致容器启动失败的风险（4/4 execvp failed 根因）
+- 文件权限由 Docker COPY 的 `--chmod=755` 保证，不受 Windows/Linux 路径转换影响
+- 符合"镜像即 immutable artifact"的最佳实践
+- 代价：开发阶段修改脚本后需要 rebuild 镜像（可接受）
+
+---
+
+## 二、可维护性审核
+
+### 2.1 文档评估
+
+| 文档 | 完整度 | 时效性 | 问题 |
+|------|--------|--------|------|
+| **ISSUES.md** | 9/10 | 最新 (2026-04-07) | 问题记录详实，含根因分析和解决方案；是项目最有价值的运维文档 |
+| **README.md** | 缺失 | N/A | **仍然缺失** -- 新人无法快速上手（P0 级缺口） |
+| **SPECS.md** | 缺失 | N/A | **无技术规格文档** -- 架构决策无书面记录 |
+| **CHANGELOG** | 缺失 | N/A | **无变更日志** -- ISSUES.md 部分承担此功能但不规范 |
+| **PACKAGES.md** | 缺失 | N/A | **仍然缺失** -- 包清单未独立维护 |
+| **API 文档** | 0/10 | 不适用 | auth-proxy.js 的 API 无文档 |
+
+#### 关键文档问题
+
+1. **缺少 README.md** -- 作为测试服部署的正式版本，没有入门文档是不可接受的。新运维人员无法知道如何构建、启动、连接。
+2. **ISSUES.md 承担了过多角色** -- 它同时充当了 CHANGELOG、FAQ、故障排查指南的角色，结构上不如独立文档清晰。
+3. **auth-proxy.js 和 login.html 无文档** -- 认证代理是安全关键组件，其工作原理、配置方法应有说明。
+
+### 2.2 代码可维护性
+
+#### 2.2.1 版本管理（硬编码集中度）
+
+| 组件 | Dockerfile | download-packages.sh | 分散度 |
+|------|-----------|---------------------|--------|
+| Node.js | v24.14.1 (musl) | v24.14.1 (musl) | 低 |
+| Claude Code | @latest (Dockerfile) | 2.1.87 (download-packages.sh) | 中 -- Dockerfile 已改用 @latest，构建时拉取最新版 |
+| coding-helper | @latest | 0.0.7 | **中 (@latest 不确定)** -- 用户决策：保持 @latest 以自动跟进更新 |
+| OpenClaw | 未安装 | 2026.3.28 (下载了但未安装) | 中 -- download-packages.sh 已补回主目录，保留下载逻辑 |
+| ttyd | (apk, 版本由仓库决定) | - | 低 |
+
+**问题状态**：
+
+1. **Claude Code 版本不一致** -- **[已解决]** Dockerfile 已改为 `@anthropic-ai/claude-code@latest`（Dockerfile:18），不再硬编码版本号。download-packages.sh 仍保留固定版本 2.1.87 用于离线缓存，两者不再冲突。
+2. **OpenClaw 下载了但未安装** -- 保持原状。download-packages.sh 已从 workpod-alpine 补回主目录，保留 OpenClaw 下载逻辑供未来使用。
+3. **coding-helper@latest** -- 用户决策保持 `@latest`，接受构建结果不确定性以换取自动更新便利。
+
+#### 2.2.2 配置管理
+
+| 配置项 | 硬编码位置 | 是否可通过环境变量覆盖 |
+|--------|-----------|---------------------|
+| SSH 密码 | Dockerfile (`ROOT_PASSWORD:-workpod123`) | **是** -- ROOT_PASSWORD 环境变量（docker-compose.yml:26） |
+| ttyd 凭据 | entrypoint.sh (`TTYD_CREDENTIALS:-jc:1234567`) | **是** -- TTYD_CREDENTIALS 环境变量（docker-compose.yml:27） |
+| ttyd 主题色 | entrypoint.sh (`#1a1a2e`) | 否 |
+| npm registry | Dockerfile (`npmmirror.com`) | 否 |
+| Claude Code 别名 | .bashrc (`--dangerously-skip-permissions` / `--allow-dangerously-skip-permissions`) | 否 |
+| 时区 | Dockerfile ENV + docker-compose | 是 |
+| 内存限制 | docker-compose | 是 |
+
+**问题状态**：
+- **SSH 密码硬编码** -- **[已改善]** Dockerfile 改为 `${ROOT_PASSWORD:-workpod123}`（Dockerfile:34），docker-compose.yml 通过环境变量传入 `ROOT_PASSWORD`。默认值仍为 workpod123 但已可外部配置。
+- **ttyd 凭据硬编码** -- **[已修复]** entrypoint.sh 改为 `${TTYD_CREDENTIALS:-jc:1234567}`（entrypoint.sh:50），docker-compose.yml 通过 `TTYD_CREDENTIALS` 环境变量传入。凭据完全外部化。
+- **两套 entrypoint 凭据不一致** -- **[不适用]** entrypoint-test.sh 已归档，当前仅保留一份 entrypoint.sh，不存在多份脚本凭据不一致问题。
+- **Claude Code 全权限别名硬编码**：`--dangerously-skip-permissions` 直接写在 .bashrc 中，无法通过环境变量控制。
+
+#### 2.2.3 当前代码规模（Alpine 主版本）
+
+> 注：Ubuntu 版已不在主目录中，不再进行跨版本对比。
+
+| 文件 | 行数 | 说明 |
+|------|------|------|
+| Dockerfile | 58 | 多阶段构建，含 ROOT_PASSWORD/TTYD_CREDENTIALS 环境变量支持 |
+| entrypoint.sh | 86 | 单一入口脚本，凭据通过 TTYD_CREDENTIALS 环境变量读取 |
+| ttyd-session.sh | 63 | ttyd 会话管理脚本（Alpine 独有） |
+| docker-compose.yml | 64 | 含 ROOT_PASSWORD/TTYD_CREDENTIALS 环境变量配置 |
+| download-packages.sh | 65 | 包下载脚本（已补回主目录） |
+| auth-proxy.js | ~173 | 认证代理（Alpine 独有） |
+
+**代码质量改善**：
+- entrypoint 从 3 份脚本（entrypoint.sh x2 + entrypoint-test.sh）精简为 **1 份**（entrypoint.sh），消除了脚本间的不一致风险。
+- 凭据统一通过环境变量注入（ROOT_PASSWORD、TTYD_CREDENTIALS），不再硬编码在多份文件中。
+
+#### 2.2.4 代码质量问题
+
+| # | 位置 | 问题 | 严重程度 | 状态 |
+|---|------|------|---------|------|
+| 1 | Dockerfile:18 vs download-packages.sh:32 | Claude Code 版本不一致（已改 @latest） | 高 | **[已解决]** -- Dockerfile 改为 @latest，不再硬编码版本号 |
+| 2 | download-packages.sh:40-48 | OpenClaw 下载但 Dockerfile 未安装 | 中 | 保持 -- download-packages.sh 已补回主目录，保留供未来使用 |
+| 3 | entrypoint.sh:50 (历史) | ttyd 凭据不一致（多脚本时代） | 中 | **[已解决]** -- 单一 entrypoint.sh + TTYD_CREDENTIALS 环境变量 |
+| 4 | Dockerfile:19 | `@z_ai/coding-helper@latest` 不确定版本 | 中 | 用户决策保持 @latest |
+| 5 | entrypoint-test.sh (已归档) | ANTHROPIC_AUTH_TOKEN 等 env 直接嵌入 .bashrc | 低 | **[不适用]** -- entrypoint-test.sh 已归档 |
+| 6 | auth-proxy.js:8 | 密码明文写死在源码中 (`1234567`, `admin123`) | **高** | 保持 -- auth-proxy.js 已补回主目录，密码外部化待后续处理 |
+| 7 | docker-compose.yml (历史) | entrypoint.sh 外挂而非内置镜像 | 中 | **[已解决]** -- 改为 COPY --chmod=755 内置到镜像 |
+
+### 2.3 运维评估
+
+#### 2.3.1 故障排查便利性
+
+| 能力 | 具备情况 | 评价 |
+|------|---------|------|
+| **健康检查** | HEALTHCHECK (netstat) + docker-compose healthcheck | 良 -- 已修复 ss->netstat 问题（见 ISSUES.md） |
+| **问题追踪** | ISSUES.md 实时记录 | **优** -- 这是项目最大的运维亮点 |
+| **结构化日志** | 无 -- 仅文本输出 | 中 |
+| **日志轮转** | json-file driver, 10m*3 | 良 |
+| **启动诊断输出** | entrypoint 打印完整版本信息（Node/npm/Claude/Rust/Go/Python） | **优** -- 比 Ubuntu 版更全面 |
+| **错误退出码** | ttyd/sshd 失败 exit 1 | 良 |
+| **监控指标** | 无 | 差 |
+| **会话恢复** | tmux + ttyd-session.sh | **优** -- 断线重连不丢失上下文 |
+
+#### 2.3.2 升级流程复杂度
+
+| 升级场景 | 步骤数 | 复杂度 |
+|---------|-------|--------|
+| 升级 Node.js | 3 步（改下载脚本 -> 下载 musl 包 -> rebuild） | 中 -- musl 包源不同 |
+| 升级 Claude Code | 3 步（需同步改 Dockerfile + download-packages.sh） | **中偏高** -- 两处版本号要一致 |
+| 升级 ttyd | 1 步（rebuild，apk 自动拉取） | 低 -- 但版本不可控 |
+| 新增开发实例 | 复制 docker-compose-alpine.yml 改端口 | 低 |
+| 同步修复到 Ubuntu | 手动对比 + 双份修改 | **高** |
+
+#### 2.3.3 回滚能力
+
+| 场景 | 回滚方式 | 可行性 |
+|------|---------|--------|
+| 镜像回滚 | `docker load < workpod-alpine-latest.tar.gz` (已存在) | **优** -- 有导出文件 |
+| 数据回滚 | /root 已 bind mount，可手动备份 | 中 |
+| 配置回滚 | git checkout | 良 |
+| 快速回退 | 无原生支持 | 中 |
+
+#### 2.3.4 测试服 4 实例运营评估
+
+| 项目 | 当前状态 | 评价 |
+|------|---------|------|
+| **镜像共享** | 4 实例共用 workpod-alpine:latest | **优** -- 存储高效 |
+| **端口规划** | 2222(SSH 基础实例), 7681(ttyd 基础实例) / 2201(SSH Flux), 7701(ttyd Flux) | 中 -- 需要文档化端口分配表 |
+| **数据隔离** | 各实例独立 data/ 目录 | **优** |
+| **认证代理** | auth-proxy.js (端口 8080) | **优** -- 统一入口 + token 认证 |
+| **负载均衡** | 无 (各实例独立端口) | 中 -- 小规模够用 |
+| **扩容** | 复制 compose 文件改端口 | 低 -- 手动但简单 |
+
+#### 2.3.5 安全评估
+
+| 项目 | 当前状态 | 风险等级 |
+|------|---------|---------|
+| privileged: true | 启用 | **高** |
+| root 用户运行 | 默认 root | **高** |
+| SSH 密码 | ROOT_PASSWORD 环境变量（默认 workpod123） | **中→改善** -- 已可外部配置 |
+| ttyd 认证 | TTYD_CREDENTIALS 环境变量（默认 jc:1234567） | **低→更好** -- 凭据完全外部化，比硬编码显著改善 |
+| auth-proxy | Basic Auth + Token | **良** -- 有认证层 |
+| auth-proxy 密码 | 明码硬编码 (1234567, admin123) | **高** -- auth-proxy.js 自身问题，待后续外部化 |
+| 端口暴露 | 2222 + 7681 (基础实例) / 2201 + 7701 (Flux 实例) | **中** |
+| developer 用户 | sudo NOPASSWD | **中** |
+| Claude Code 全权限 | --dangerously-skip-permissions 默认开启 | **中** |
+
+---
+
+## 三、综合评分
+
+| 维度 | Alpine 版得分 | 说明 |
+|------|-------------|------|
+| **性能** | **8.5/10** | 镜像极小(436MB)、内存占用低、多阶段构建优秀；entrypoint 已内置镜像（+0.5）；privileged 仍扣分 |
+| **可维护性** | **6/10** | 较上期 +1：版本统一(@latest)、凭据外部化(ROOT_PASSWORD/TTYD_CREDENTIALS)、单 entrypoint 脚本、entrypoint 内置镜像；仍缺 README/SPECS/PACKAGES、@latest tag 不确定、auth-proxy 密码未外部化 |
+| **文档** | **4/10** | ISSUES.md 一枝独秀(9/10)；但零 README（仍然缺失）、零 SPECS、零 CHANGELOG、零 PACKAGES，新人完全无法入手 |
+| **运维** | **6.5/10** | 较上期 +0.5：健康检查完善、问题追踪及时、tmux 会话管理优秀、认证代理加分、凭据可配置化改善运维体验；无监控、安全配置有改进空间 |
+| **总分** | **25/40** | 性能突出，可维护性和运维较上期有实质改善；文档短板仍是最大拖累，属于"技术优秀、工程化持续改善中"水平 |
+
+---
+
+## 四、优先改进项（按 ROI 排序）
+
+| # | 改进项 | 影响 | 成本 | ROI | 说明 |
+|---|--------|------|------|-----|------|
+| 1 | **创建 README.md** | 新人可快速上手 | 低 | **极高** | **仍然是 P0** -- 作为测试服正式版本，这是最紧迫的缺口 |
+| 2 | ~~统一 Claude Code 版本号~~ | 消除构建不确定性 | 极低 | **极高** | **[完成]** -- Dockerfile 已改为 @latest，不再硬编码版本号 |
+| 3 | ~~移除 OpenClaw 下载或安装它~~ | 消除无用依赖 | 极低 | 高 | **降级** -- download-packages.sh 已补回主目录，保留下载逻辑供未来使用；不再紧迫 |
+| 4 | **提取 entrypoint 公共模块** | 消除重复代码 | 中 | 中 | **优先级降低** -- 当前仅单 entrypoint 场景（entrypoint-test.sh 已归档），跨版本同步成本已消除 |
+| 5 | ~~统一 ttyd 凭据管理~~ | 消除配置混乱 | 低 | **高** | **[完成]** -- TTYD_CREDENTIALS 环境变量已实现凭据外部化 |
+| 6 | **auth-proxy 密码外部化** | 消除安全隐患 | 低 | **高** | auth-proxy.js 明文密码待改为环境变量或配置文件读取 |
+| 7 | **coding-helper 改固定版本** | 构建可重现 | 极低 | **中** | 用户当前选择保持 @latest，如需可重现构建则替换为具体版本号 |
+| 8 | ~~将 entrypoint.sh 内置到镜像~~ | 符合 immutable 镜像最佳实践 | 低 | **中** | **[完成]** -- COPY --chmod=755 已实现内置 |
+| 9 | **添加 SPECS.md / PACKAGES.md** | 文档体系完善 | 中 | **中** | 多阶段架构、认证代理设计、包清单值得记录 |
+| 10 | **评估取消 privileged** | 安全性提升 | 中 | 测试是否真正需要，尝试 `--cap-add SYS_ADMIN` 等细粒度替代 |
+
+---
+
+## 五、与 Ubuntu 版对比摘要
+
+| 维度 | Alpine 版 | Ubuntu 版 | 胜出者 |
+|------|----------|-----------|--------|
+| 镜像大小 | 436 MB | 2.6 GB | **Alpine (6x)** |
+| 内存基线 | ~80 MB | ~400 MB | **Alpine (5x)** |
+| 构架先进性 | 多阶段构建 | 单阶段构建 | **Alpine** |
+| 功能完整性 | 含 tmux session 管理 | 含 OpenClaw | 各有侧重 |
+| 安全性(ttyd) | 有认证 (-c) | 无认证 (-W) | **Alpine** |
+| 文档体系 | ISSUES.md 优秀但单一 | SPECS+PACKAGES+REVIEW 较全 | **Ubuntu (广度)** |
+| 文档时效性 | ISSUES 实时更新 | SPECS 过时 | **Alpine** |
+| 代码重复度 | 高（3 份脚本） | 中（2 份脚本） | 都差 |
+| 版本一致性 | 有偏差（Claude Code） | 基本一致 | **Ubuntu** |
+| 生产就绪度 | 测试服 4 实例运行中 | 本地开发为主 | **Alpine** |
+
+**结论**：Alpine 版在性能和生产适用性上是明确的胜出者。其主要债务在于文档缺失（尤其是 README）和版本号不一致。建议以 Alpine 版为主线版本，Ubuntu 版降级为本地调试辅助版本。
+
+---
+
+## 六、附录：auth-proxy.js 架构评审
+
+auth-proxy.js 是 Alpine 版独有的认证代理组件，值得单独关注。
+
+### 架构概览
+
+```
+浏览器 --> :8080 auth-proxy.js --> :7681 ttyd 实例
+              |-- /login        登录页
+              |-- /auth/check   Basic Auth -> Token
+              |-- /api/workspaces 工作空间列表
+              |-- /*            Token 验证 -> 代理到对应 ttyd
+              |-- (WebSocket)   upgrade -> 双向管道
+```
+
+### 优点
+- 轻量实现（173 行），无第三方依赖
+- Token 机制（1 小时过期）避免密码反复传输
+- WebSocket 代理支持终端正常工作
+- 多工作空间路由
+
+### 风险点
+| # | 风险 | 说明 |
+|---|------|------|
+| 1 | **Token 存储在内存** | 进程重启后所有 Token 失效，用户需重新登录 |
+| 2 | **密码明文硬编码** | `VALID_PASSWORDS = { wk: '1234567', admin: 'admin123' }` |
+| 3 | **无 HTTPS** | 密码和 Token 明文传输 |
+| 4 | **单进程无集群** | 无法横向扩展 |
+| 5 | **无速率限制** | 暴力破解密码无防护 |
+
+### 建议
+- 密码改为环境变量：`process.env.AUTH_PASSWORDS`
+- 生产环境前置 nginx/Terminus 做 HTTPS 结束
+- 添加登录失败次数限制（内存计数器即可）