# 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`