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

docs/02-技术文档/ISSUES.md

@@ -0,0 +1,122 @@
+# WorkPod Alpine 问题记录
+
+> 最后更新：2026-04-02
+
+---
+
+## Alpine 无 `ss` 命令
+
+HEALTHCHECK 使用 `ss -tlnp` 报错 `ss: not found`。
+
+**解决**：改用 busybox 内置的 `netstat -tlnp`。
+
+---
+
+## docker-compose healthcheck 覆盖镜像 HEALTHCHECK
+
+修复了 Dockerfile 中的 HEALTHCHECK，但容器仍报 `ss` 错误。
+
+**原因**：docker-compose.yml 中的 `healthcheck:` 字段会覆盖镜像的 HEALTHCHECK 指令。
+
+**解决**：同步修改 docker-compose.yml 中的 healthcheck 命令。
+
+---
+
+## `COPY --chmod` 需要 BuildKit
+
+`COPY --chmod=755 entrypoint.sh /entrypoint.sh` 报错 `the --chmod option requires BuildKit`。
+
+**解决**：拆为两步：
+```dockerfile
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod 755 /entrypoint.sh
+```
+
+---
+
+## BuildKit 缓存不失效 HEALTHCHECK
+
+修改 HEALTHCHECK 后重新 build，镜像中仍是旧命令。
+
+**原因**：BuildKit 缓存了 HEALTHCHECK 的 metadata 层。
+
+**解决**：使用 `DOCKER_BUILDKIT=0` 经典构建器。
+
+---
+
+## ttyd execvp failed: No such file or directory
+
+ttyd 启动命令使用了容器中不存在的程序（如 `claude`、`tmux`）。
+
+**原因**：ttyd 子进程的 PATH 可能不完整，或镜像未安装对应软件。
+
+**解决**：确保 ttyd 启动的命令在镜像中已安装，且使用完整路径或先验证可用性。
+
+---
+
+## ttyd 静态资源 404
+
+浏览器访问 ttyd 时 `style.css`、`js` 等 404。
+
+**说明**：ttyd 1.7.4 将资源内联到 HTML 中，单独文件的 404 是预期行为，页面功能正常。
+
+---
+
+## 容器重建丢失数据
+
+`docker compose down && up` 后 /root 下的 Rust 安装等文件丢失。
+
+**原因**：只有 bind mount 的路径才会持久化，未挂载的目录随容器销毁。
+
+**解决**：将需要持久化的目录通过 volumes 挂载。
+
+---
+
+## ttyd 断线后会话丢失
+
+ttyd 默认启动 `bash`，断线后进程被 kill，会话无法恢复。
+
+**解决**：使用 `tmux new -A -s workpod` 替代 `bash`，需要镜像安装 `tmux`。
+
+---
+
+## Web 终端中文输入不了
+
+ttyd + tmux 环境下无法输入中文字符。
+
+**原因**：容器未设置 `LANG` 环境变量，终端无 UTF-8 编码支持。
+
+**解决**：添加 `LANG=C.UTF-8` 到 Dockerfile ENV 和 docker-compose environment。
+
+---
+
+## tmux 多用户共享同一 session
+
+使用 `tmux new -A -s workpod` 时所有用户进入同一个 session，互相可见。
+
+**解决**：通过 `ttyd-session.sh` 脚本实现 session 选择——支持 URL 参数 `?session=name` 直接进入，或交互式菜单选择/创建。
+
+注意：`tmux attach-session -d` 会踢掉旧连接，应使用 `tmux attach-session`（不加 `-d`）实现共享模式。
+
+---
+
+## 容器重建后手动安装的工具丢失
+
+在容器内手动安装的工具，解压到 `/usr/local` 等非挂载目录的会在重建后丢失。
+
+**解决**：所有工具解压到 `/root` 下，entrypoint 自动检测并设置 PATH。
+
+### 安装方式
+
+| 工具 | 安装命令 | 存储位置 |
+|------|---------|---------|
+| Rust | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` | `/root/.cargo` `/root/.rustup` |
+| Python | `curl https://pyenv.run` | `/root/.pyenv` |
+| Go | `tar -xzf go1.xx.linux-amd64.tar.gz -C /root` | `/root/go` |
+| pip 用户包 | `pip install --user xxx` | `/root/.local` |
+
+### 原则
+
+- 解压目录用 `/root` 而不是 `/usr/local`
+- 不要用 `apk add` 装开发工具（重建会丢），需要的加到 Dockerfile
+- entrypoint 自动检测 `/root` 下的工具目录，写入 `/etc/profile.d/dev-tools.sh`