Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(sandbox): support Docker Desktop socket permissions (#3088)

helloxjade36de0d2d580e
diff --git a/.github/workflows/app.yml b/.github/workflows/app.yml
index c93390392..f37170cd0 100644
--- a/.github/workflows/app.yml
+++ b/.github/workflows/app.yml
@@ -22,6 +22,8 @@ on:
- "website-docs/0*/**"
- "website-docs/.vitepress/config.mts"
- "docker/Dockerfile.app"
+ - "scripts/docker-entrypoint.sh"
+ - "scripts/docker-entrypoint_test.sh"
- "LICENSE"
- "THIRD_PARTY_NOTICES.md"
- "licenses/**"
@@ -52,6 +54,8 @@ on:
- "website-docs/0*/**"
- "website-docs/.vitepress/config.mts"
- "docker/Dockerfile.app"
+ - "scripts/docker-entrypoint.sh"
+ - "scripts/docker-entrypoint_test.sh"
- "LICENSE"
- "THIRD_PARTY_NOTICES.md"
- "licenses/**"
@@ -100,6 +104,8 @@ jobs:
- name: Download modules
run: go mod download
+ - name: Test Docker entrypoint permissions
+ run: bash scripts/docker-entrypoint_test.sh
- name: Verify third-party notices and source bundle
run: |
bash ./scripts/check-license-bundle.sh
diff --git a/Makefile b/Makefile
index 286bf2d2e..9009aedd1 100644
--- a/Makefile
+++ b/Makefile
@@ -110,6 +110,7 @@ run: build
# Run tests
test:
+ bash scripts/docker-entrypoint_test.sh
go test -v ./...
# Generate reviewed metadata + protocol overrides, then verify every model.
diff --git a/scripts/docker-entrypoint.sh b/scripts/docker-entrypoint.sh
index 504f0d636..d3088bb42 100755
--- a/scripts/docker-entrypoint.sh
+++ b/scripts/docker-entrypoint.sh
@@ -13,31 +13,35 @@ MOUNT_DIRS=(
/data/files
)
-for dir in "${MOUNT_DIRS[@]}"; do
- if [ -d "$dir" ]; then
- chown -R appuser:appuser "$dir" 2>/dev/null || true
- fi
-done
-
# ─── Docker socket access for the sandbox backend ───
-# The Engine API socket is typically root:docker 0660. This process then
-# drops to appuser via gosu, which calls initgroups and therefore drops
-# compose group_add. Match the socket's GID in /etc/group before gosu.
-# Never chmod the host socket: that would weaken daemon access on the host.
+# The Engine API socket is typically root:docker 0660. Docker Desktop exposes
+# its socket inside Linux containers as root:root 0660, so GID 0 is valid when
+# the group bits really grant read/write access. This process drops to appuser
+# via gosu, which calls initgroups and therefore drops compose group_add. Match
+# the socket's GID in /etc/group before gosu. Never chmod or chown the mounted
+# socket: that would change the security boundary outside this container.
grant_docker_sock_to_appuser() {
local sock="$1"
- local gid grp
+ local gid mode grp
[ -S "$sock" ] || return 0
- if gosu appuser sh -c "test -r \"$sock\" && test -w \"$sock\"" 2>/dev/null; then
+ if gosu appuser test -r "$sock" 2>/dev/null &&
+ gosu appuser test -w "$sock" 2>/dev/null; then
return 0
fi
- gid="$(stat -c '%g' "$sock" 2>/dev/null || true)"
- if [ -z "$gid" ]; then
+ gid="$(stat -c '%g' -- "$sock" 2>/dev/null || true)"
+ mode="$(stat -c '%a' -- "$sock" 2>/dev/null || true)"
+ if [ -z "$gid" ] || [ -z "$mode" ]; then
echo "weknora: cannot stat $sock; Docker sandbox may be unable to reach the daemon" >&2
return 0
fi
- if [ "$gid" = "0" ]; then
- echo "weknora: $sock is not writable by appuser and owned by GID 0; Docker sandbox needs a group-writable socket with a non-root GID" >&2
+ case "$mode" in
+ *[!0-7]*)
+ echo "weknora: invalid mode $mode for $sock; Docker sandbox may be unable to reach the daemon" >&2
+ return 0
+ ;;
+ esac
+ if (( (8#$mode & 0060) != 0060 )); then
+ echo "weknora: $sock is not group-readable and group-writable; refusing to change socket permissions" >&2
return 0
fi
if ! getent group "$gid" >/dev/null 2>&1; then
@@ -57,12 +61,25 @@ grant_docker_sock_to_appuser() {
fi
}
-grant_docker_sock_to_appuser /var/run/docker.sock
-case "${DOCKER_HOST:-}" in
- unix://*)
- grant_docker_sock_to_appuser "${DOCKER_HOST#unix://}"
- ;;
-esac
+main() {
+ local dir
+ for dir in "${MOUNT_DIRS[@]}"; do
+ if [ -d "$dir" ]; then
+ chown -R appuser:appuser "$dir" 2>/dev/null || true
+ fi
+ done
+
+ grant_docker_sock_to_appuser /var/run/docker.sock
+ case "${DOCKER_HOST:-}" in
+ unix://*)
+ grant_docker_sock_to_appuser "${DOCKER_HOST#unix://}"
+ ;;
+ esac
+
+ # ─── Drop privileges and exec the main process ───
+ exec gosu appuser "$@"
+}
-# ─── Drop privileges and exec the main process ───
-exec gosu appuser "$@"
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+ main "$@"
+fi
diff --git a/scripts/docker-entrypoint_test.sh b/scripts/docker-entrypoint_test.sh
new file mode 100644
index 000000000..1703769fd
--- /dev/null
+++ b/scripts/docker-entrypoint_test.sh
@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=docker-entrypoint.sh
+source "$SCRIPT_DIR/docker-entrypoint.sh"
+
+TEST_DIR="$(mktemp -d)"
+SOCKET_PATH="$TEST_DIR/docker.sock"
+SOCKET_PID=""
+
+cleanup() {
+ if [ -n "$SOCKET_PID" ]; then
+ kill "$SOCKET_PID" 2>/dev/null || true
+ wait "$SOCKET_PID" 2>/dev/null || true
+ fi
+ rm -rf "$TEST_DIR"
+}
+trap cleanup EXIT
+
+python3 -c '
+import socket
+import sys
+import time
+
+sock = socket.socket(socket.AF_UNIX)
+sock.bind(sys.argv[1])
+time.sleep(60)
+' "$SOCKET_PATH" &
+SOCKET_PID=$!
+
+for _ in $(seq 1 50); do
+ [ -S "$SOCKET_PATH" ] && break
+ sleep 0.02
+done
+[ -S "$SOCKET_PATH" ] || {
+ echo "test setup failed: unix socket was not created" >&2
+ exit 1
+}
+
+FAKE_GID=""
+FAKE_MODE=""
+FAKE_ACCESSIBLE=0
+GOSU_CALLS=()
+GROUPADD_CALLS=()
+USERMOD_CALLS=()
+
+gosu() {
+ GOSU_CALLS+=("$*")
+ [ "$FAKE_ACCESSIBLE" -eq 1 ]
+}
+
+stat() {
+ case "$*" in
+ *%g*) printf '%s\n' "$FAKE_GID" ;;
+ *%a*) printf '%s\n' "$FAKE_MODE" ;;
+ *) command stat "$@" ;;
+ esac
+}
+
+getent() {
+ if [ "$1" = "group" ] && [ "$2" = "0" ]; then
+ printf 'root:x:0:\n'
+ return 0
+ fi
+ if [ "$1" = "group" ] && [ "$2" = "1234" ]; then
+ printf 'dockersock:x:1234:\n'
+ return 0
+ fi
+ return 2
+}
+
+groupadd() {
+ GROUPADD_CALLS+=("$*")
+}
+
+usermod() {
+ USERMOD_CALLS+=("$*")
+}
+
+reset_case() {
+ FAKE_GID="$1"
+ FAKE_MODE="$2"
+ FAKE_ACCESSIBLE="${3:-0}"
+ GOSU_CALLS=()
+ GROUPADD_CALLS=()
+ USERMOD_CALLS=()
+}
+
+assert_equal() {
+ local want="$1"
+ local got="$2"
+ local message="$3"
+ if [ "$got" != "$want" ]; then
+ printf 'FAIL: %s\n want: %s\n got: %s\n' "$message" "$want" "$got" >&2
+ exit 1
+ fi
+}
+
+reset_case 0 660
+grant_docker_sock_to_appuser "$SOCKET_PATH"
+assert_equal "-aG root appuser" "${USERMOD_CALLS[*]:-}" \
+ "Docker Desktop root:root 0660 socket should grant the existing root group"
+assert_equal "appuser test -r $SOCKET_PATH" "${GOSU_CALLS[0]:-}" \
+ "socket checks should pass paths as arguments, not through sh -c"
+
+reset_case 0 600
+grant_docker_sock_to_appuser "$SOCKET_PATH" 2>"$TEST_DIR/mode-error"
+assert_equal "" "${USERMOD_CALLS[*]:-}" \
+ "root:root 0600 socket must remain inaccessible"
+grep -q "not group-readable and group-writable" "$TEST_DIR/mode-error"
+
+reset_case 1234 660
+grant_docker_sock_to_appuser "$SOCKET_PATH"
+assert_equal "-aG dockersock appuser" "${USERMOD_CALLS[*]:-}" \
+ "existing non-root socket groups should keep working"
+
+reset_case 0 660 1
+grant_docker_sock_to_appuser "$SOCKET_PATH"
+assert_equal "" "${USERMOD_CALLS[*]:-}" \
+ "an already-accessible socket should not change group membership"
+
+echo "docker-entrypoint socket permission tests: PASS"
diff --git a/website-docs/01-getting-started/02-installation.md b/website-docs/01-getting-started/02-installation.md
index 5504fca60..e340130c0 100644
--- a/website-docs/01-getting-started/02-installation.md
+++ b/website-docs/01-getting-started/02-installation.md
@@ -185,7 +185,7 @@ PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST=https://your-playwright-mirror.example.com \
| `scripts/build_images.sh` | 构建镜像并注入版本(git tag / commit / build time),支持跨架构 |
| `scripts/build_frontend_dist.sh` | 宿主机构建前端静态产物 `frontend/dist`(Lite / 桌面打包等非 Docker 场景;UI 镜像改由 Dockerfile 多阶段构建) |
| `scripts/migrate.sh` | golang-migrate 封装 |
-| `scripts/docker-entrypoint.sh` | app 容器入口(属主修复 + docker.sock GID 补组 + gosu 降权) |
+| `scripts/docker-entrypoint.sh` | app 容器入口(属主修复 + 在不修改 socket 权限的前提下按可读写 GID 补组 + gosu 降权,兼容 Docker Desktop 的 `root:root 0660` 映射) |
| `scripts/package-lite.sh` / `package-mac-app.sh` | Lite tarball / macOS .app 打包 |
## 六、Helm 部署(helm/)
diff --git a/website-docs/06-development/04-sandbox-deployment.md b/website-docs/06-development/04-sandbox-deployment.md
index 3470f74c0..50ca869c0 100644
--- a/website-docs/06-development/04-sandbox-deployment.md
+++ b/website-docs/06-development/04-sandbox-deployment.md
@@ -32,7 +32,7 @@ Docker 后端默认关闭。系统管理员在「系统设置 → 网络安全
| 网络模式 | 仅 `bridge` 或 `none`;不接受 `host`、`container:` 或自定义网络名 |
| OCI runtime | 可选择 daemon 已安装的 runtime,如 `runsc` |
-app 运行在容器里时,要挂载实际 Docker socket,或改连远端 daemon。socket 授予控制宿主机 Docker 的能力,只应交给可信 app。入口脚本在降权前根据 socket GID 配置 appuser 的组;不要通过 `chmod 666` 放开 socket。若 socket 为 `root:root` 且仅所有者可写,应先在宿主机配置合适的非 root 组权限。
+app 运行在容器里时,要挂载实际 Docker socket,或改连远端 daemon。socket 授予控制宿主机 Docker 的能力,只应交给可信 app。入口脚本在降权前根据 socket GID 配置 appuser 的组;不要依赖 compose `group_add`,也不要通过 `chmod 666` 放开 socket。Docker Desktop 可能把 socket 映射为 `root:root 0660`;入口脚本会先确认组读写位,再把 appuser 加入对应的补充组。若 socket 为 `root:root 0600` 等仅所有者可写模式,入口脚本不会修改其属主或权限,部署方应改用组可读写的 socket 或带 TLS 的远端 daemon。
优先使用标准镜像。自定义镜像需满足适配器的 root、Bash、GNU `find -printf`、coreutils `timeout` 和可写工作区要求;会话文件检查点与回退还依赖 Git。HTTP 请求取消本身不会终止容器进程,适配器通过容器内 `timeout` 执行命令超时控制。