Add more content

2026-03-10 11:54:37 +00:00 · 2026-01-30 16:48:39 -08:00
parent c58f61dbed
commit fec2e506d9
39 changed files with 8202 additions and 1063 deletions
--- a/image/dockerfile/user.md
+++ b/image/dockerfile/user.md
@@ -1,26 +1,273 @@
 # USER 指定当前用户

-格式：`USER <用户名>[:<用户组>]`
-
-`USER` 指令和 `WORKDIR` 相似，都是改变环境状态并影响以后的层。`WORKDIR` 是改变工作目录，`USER` 则是改变之后层的执行 `RUN`, `CMD` 以及 `ENTRYPOINT` 这类命令的身份。
-
-注意，`USER` 只是帮助你切换到指定用户而已，这个用户必须是事先建立好的，否则无法切换。
+## 基本语法

 ```docker
-RUN groupadd -r redis && useradd -r -g redis redis
-USER redis
-RUN [ "redis-server" ]
+USER <用户名>[:<用户组>]
+USER <UID>[:<GID>]
 ```

-如果以 `root` 执行的脚本，在执行期间希望改变身份，比如希望以某个已经建立好的用户来运行某个服务进程，不要使用 `su` 或者 `sudo`，这些都需要比较麻烦的配置，而且在 TTY 缺失的环境下经常出错。建议使用 [`gosu`](https://github.com/tianon/gosu)。
+`USER` 指令切换后续指令（RUN、CMD、ENTRYPOINT）的执行用户。
+
+---
+
+## 为什么要使用 USER
+
+> 笔者强调：以非 root 用户运行容器是最重要的安全实践之一。
+
+```
+root 用户运行的风险：
+┌────────────────────────────────────────────────────────┐
+│  容器内 root  ←─ 可能逃逸 ─→  宿主机 root             │
+│      │                            │                    │
+│      └── 漏洞利用 ───────────────→ 完全控制宿主机     │
+└────────────────────────────────────────────────────────┘
+
+非 root 用户运行：
+┌────────────────────────────────────────────────────────┐
+│  容器内普通用户  ──逃逸后──→  宿主机普通用户          │
+│      │                            │                    │
+│      └── 权限受限，危害降低 ─────→ 无法控制系统       │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 基本用法
+
+### 创建并切换用户

 ```docker
-# 建立 redis 用户，并使用 gosu 换另一个用户执行命令
-RUN groupadd -r redis && useradd -r -g redis redis
-# 下载 gosu
-RUN wget -O /usr/local/bin/gosu "https://github.com/tianon/gosu/releases/download/1.12/gosu-amd64" \
-    && chmod +x /usr/local/bin/gosu \
-    && gosu nobody true
-# 设置 CMD，并以另外的用户执行
-CMD [ "exec", "gosu", "redis", "redis-server" ]
+FROM node:20-alpine
+
+# 1. 创建用户和组
+RUN addgroup -g 1001 appgroup && \
+    adduser -u 1001 -G appgroup -D appuser
+
+# 2. 设置目录权限
+WORKDIR /app
+COPY --chown=appuser:appgroup . .
+
+# 3. 切换用户
+USER appuser
+
+# 4. 后续命令以 appuser 身份运行
+CMD ["node", "server.js"]
 ```
+
+### 使用 UID/GID
+
+```docker
+# 也可以使用数字
+USER 1001:1001
+```
+
+---
+
+## 用户必须已存在
+
+`USER` 指令只能切换到**已存在**的用户：
+
+```docker
+# ❌ 错误：用户不存在
+USER nonexistent
+# Error: unable to find user nonexistent
+
+# ✅ 正确：先创建用户
+RUN useradd -r -s /bin/false appuser
+USER appuser
+```
+
+### 创建用户的方式
+
+**Debian/Ubuntu**：
+
+```docker
+RUN groupadd -r appgroup && \
+    useradd -r -g appgroup appuser
+```
+
+**Alpine**：
+
+```docker
+RUN addgroup -g 1001 -S appgroup && \
+    adduser -u 1001 -S -G appgroup appuser
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-r` (useradd) / `-S` (adduser) | 创建系统用户 |
+| `-g` | 指定主组 |
+| `-G` | 指定附加组 |
+| `-u` | 指定 UID |
+| `-s /bin/false` | 禁用登录 shell |
+
+---
+
+## 运行时切换用户
+
+### 使用 gosu（推荐）
+
+在 ENTRYPOINT 脚本中切换用户时，不要使用 `su` 或 `sudo`，应使用 [gosu](https://github.com/tianon/gosu)：
+
+```docker
+FROM debian:bookworm
+
+# 创建用户
+RUN groupadd -r redis && useradd -r -g redis redis
+
+# 安装 gosu
+RUN apt-get update && apt-get install -y gosu && rm -rf /var/lib/apt/lists/*
+
+COPY docker-entrypoint.sh /usr/local/bin/
+ENTRYPOINT ["docker-entrypoint.sh"]
+CMD ["redis-server"]
+```
+
+**docker-entrypoint.sh**：
+
+```bash
+#!/bin/bash
+set -e
+
+# 以 root 执行初始化
+chown -R redis:redis /data
+
+# 用 gosu 切换到 redis 用户运行服务
+exec gosu redis "$@"
+```
+
+### 为什么不用 su/sudo
+
+| 问题 | su/sudo | gosu |
+|------|---------|------|
+| TTY 要求 | 需要 | 不需要 |
+| 信号传递 | 不正确 | 正确 |
+| 子进程 | 是 | exec 替换 |
+| 容器中使用 | ❌ | ✅ |
+
+---
+
+## 运行时覆盖用户
+
+使用 `-u` 或 `--user` 参数：
+
+```bash
+# 以指定用户运行
+$ docker run -u 1001:1001 myimage
+
+# 以 root 运行（调试时）
+$ docker run -u root myimage
+```
+
+---
+
+## 文件权限处理
+
+切换用户后，确保应用有权访问文件：
+
+```docker
+FROM node:20-alpine
+
+# 创建用户
+RUN adduser -D -u 1001 appuser
+
+WORKDIR /app
+
+# 方式1：使用 --chown
+COPY --chown=appuser:appuser . .
+
+# 方式2：手动 chown（减少层数）
+# COPY . .
+# RUN chown -R appuser:appuser /app
+
+USER appuser
+CMD ["node", "server.js"]
+```
+
+---
+
+## 最佳实践
+
+### 1. 始终使用非 root 用户
+
+```docker
+# ✅ 推荐
+RUN adduser -D appuser
+USER appuser
+CMD ["myapp"]
+
+# ❌ 避免
+CMD ["myapp"]  # 以 root 运行
+```
+
+### 2. 使用固定 UID/GID
+
+便于在宿主机和容器间共享文件：
+
+```docker
+# 使用常见的非 root UID
+RUN addgroup -g 1000 -S appgroup && \
+    adduser -u 1000 -S -G appgroup appuser
+USER 1000:1000
+```
+
+### 3. 多阶段构建中的 USER
+
+```docker
+# 构建阶段可以用 root
+FROM node:20 AS builder
+WORKDIR /app
+COPY . .
+RUN npm install && npm run build
+
+# 生产阶段用非 root
+FROM node:20-alpine
+RUN adduser -D appuser
+WORKDIR /app
+COPY --from=builder --chown=appuser:appuser /app/dist .
+USER appuser
+CMD ["node", "server.js"]
+```
+
+---
+
+## 常见问题
+
+### Q: 权限被拒绝
+
+```bash
+permission denied: '/app/data.log'
+```
+
+**解决**：确保目录权限正确
+
+```docker
+RUN mkdir -p /app/data && chown appuser:appuser /app/data
+```
+
+### Q: 无法绑定低于 1024 的端口
+
+非 root 用户无法绑定 80、443 等端口。
+
+**解决**：
+1. 使用高端口（如 8080）
+2. 在运行时映射端口：`docker run -p 80:8080`
+
+---
+
+## 本章小结
+
+| 要点 | 说明 |
+|------|------|
+| **作用** | 切换后续指令的执行用户 |
+| **语法** | `USER username` 或 `USER UID:GID` |
+| **前提** | 用户必须已存在 |
+| **运行时覆盖** | `docker run -u` |
+| **切换工具** | 使用 gosu，不用 su/sudo |
+
+## 延伸阅读
+
+- [安全](../../security/README.md)：容器安全实践
+- [ENTRYPOINT](entrypoint.md)：入口脚本中的用户切换
+- [最佳实践](../../appendix/best_practices.md)：Dockerfile 安全