argus/doc/build-user-config.md

Argus 镜像构建 UID/GID 配置说明

通过统一配置文件可以为 Kibana、Elasticsearch、Bind、Master 等容器指定运行账号，解决跨机器部署时 UID/GID 不一致导致的权限问题。

配置入口

• 默认配置存放在 configs/build_user.conf，内容示例：

  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 强制覆盖。