yuyr
1e5e91b193
Reviewed-on: #17 Reviewed-by: sundapeng <sundp@mail.zgclab.edu.cn> Reviewed-by: xuxt <xuxt@zgclab.edu.cn>
39 lines
2.5 KiB
Markdown
39 lines
2.5 KiB
Markdown
# Argus 镜像构建 UID/GID 配置说明
|
||
|
||
通过统一配置文件可以为 Kibana、Elasticsearch、Bind、Master 等容器指定运行账号，解决跨机器部署时 UID/GID 不一致导致的权限问题。
|
||
|
||
## 配置入口
|
||
|
||
- 默认配置存放在 `configs/build_user.conf`，内容示例：
|
||
|
||
```bash
|
||
UID=2133
|
||
GID=2015
|
||
```
|
||
|
||
- 如果需要本地覆盖，可在 `configs/` 下新建 `build_user.local.conf`，字段与默认文件一致。该文件已列入 `.gitignore`，不会被意外提交。
|
||
- 亦可在执行脚本前通过环境变量 `ARGUS_BUILD_UID` / `ARGUS_BUILD_GID` 强制指定值，优先级最高。
|
||
|
||
## 作用范围
|
||
|
||
- `build/build_images.sh` 在构建 log/bind/master 镜像时读取配置，并传递 `--build-arg ARGUS_BUILD_UID/GID`；控制台会输出当前使用的 UID/GID。
|
||
- `src/master/scripts/build_images.sh` 同步使用配置，确保单独构建 master 镜像时行为一致。
|
||
- 各镜像 Dockerfile 会根据传入的 UID/GID 调整容器内账号（如 `elasticsearch`、`kibana`、`bind`、`argus`），并以环境变量形式暴露运行时可见值。
|
||
- Master 启动脚本会在执行 DNS 逻辑后，降权到配置的账号运行 `gunicorn`，确保写入 `/private/argus/**` 的文件具备正确属主。
|
||
- Log 模块测试脚本 `01_bootstrap.sh` 会根据配置修正挂载目录属主，方便端到端测试在任意用户下运行。
|
||
|
||
## 使用建议
|
||
|
||
1. 初次克隆仓库后无需修改，默认 UID/GID 保持向后兼容。
|
||
2. 如果在目标环境中使用新的账号（例如 `uid=4001,gid=4001`）：
|
||
- 编辑 `configs/build_user.local.conf` 填入新值；
|
||
- 使用新账号登录，并确保其加入宿主机的 `docker` 组；
|
||
- 重新执行 `build/build_images.sh` 或相关模块的构建脚本。
|
||
3. 切换配置后建议重新运行目标模块的端到端脚本（如 `src/log/tests/scripts/01_bootstrap.sh`、`src/master/tests/scripts/00_e2e_test.sh`、`src/agent/tests/scripts/00_e2e_test.sh`），验证 `/private/argus` 下文件属主是否为期望账号。
|
||
|
||
## 故障排查
|
||
|
||
- **镜像构建报错 `groupmod: GID already in use`**：说明所选 GID 已存在于基础镜像，建议换用未占用的值，或在自定义基础镜像中先移除冲突。
|
||
- **容器内运行时报写权限不足**：检查宿主机挂载目录是否已经由目标 UID/GID 创建；必要时重新执行模块的 `01_bootstrap.sh` 之类的准备脚本。
|
||
- **仍看到旧 UID/GID**：确认脚本执行时未继承旧缓存，可运行 `ARGUS_BUILD_UID=... ARGUS_BUILD_GID=... ./build/build_images.sh` 强制覆盖。
|