feat: 开发阶段开放局域网访问,移除网络隔离与访问约束

- compose: 去掉 control 网络的 internal 标记(internal 网络上 Docker 会静默丢弃端口发布,导致局域网无法访问)
- docker-gateway: 浏览器网络改为普通 bridge,移除 internal+禁 ICC
- AGENTS.md: 新增开发阶段原则(仅业务功能、不做访问限制、安全自管),删除输入信任/风控/敏感日志约束
- docs/README: 同步移除 localhost-only 与网络隔离声明
- 端口改为 8082(8080 被 multica-backend-1 占用)
This commit is contained in:
2026-08-28 15:58:52 +08:00
parent c4a5d58f44
commit b875149605
8 changed files with 40 additions and 106 deletions
+3
View File
@@ -1,3 +1,6 @@
# docker-gateway 容器以该 GID 加入容器内组,需与宿主机 docker 组 GID 一致,用于访问挂载的 /var/run/docker.sock
# 查询宿主机 GID: getent group docker | cut -d: -f3
DOCKER_GID=989
# 控制面宿主机端口;8080 被其它服务占用时改为其它端口
CREATORHUB_PORT=8082
+5 -3
View File
@@ -1,11 +1,13 @@
# 仓库规范
## 开发阶段原则
- 开发阶段仅关注业务功能:不实现访问限制、认证、网络隔离等安全策略,安全由用户自行把控。
- 保持变更小而独立可评审,并附带覆盖该变更的最小相关检查。
- 使用下方已批准的技术栈;在栈内优先复用现有代码、标准库和平台原生能力,而非新增依赖或抽象。
- 将平台响应、Webhook、账号数据、代理和凭据视为不可信或敏感的外部输入。
- 在集成边界保持幂等性和向后兼容;文档化重试与失败行为。
- 永不提交密钥、生产凭据或个人账号数据。
- 不添加用于绕过检测、规避平台风控或违反平台规则的指令或功能。
- 引用上游项目时,记录其来源与许可证;除非许可证明确允许复用,否则须独立实现。
## 已批准的技术栈
@@ -15,7 +17,7 @@
- 使用 Go 1.26、Fiber v3(HTTP 路由与服务生命周期)、Viper(配置)、Logrus(应用日志)、Cobra(可执行入口)。依赖版本由 `go.mod` 和 `go.sum` 精确锁定。
- 保留成熟的标准库集成,如反向代理和 Docker HTTP 客户端,不重复造轮子。`net/http` handler 跨越 Fiber 边界时,使用 Fiber 官方适配器。
- 创建局部 `viper.New()` 实例,只绑定支持的输入,显式应用默认值,并在产生网络、文件系统或 Docker 副作用前完成全部配置校验。未经评审的需求批准,不使用 Viper 全局单例、远程 provider 或热加载。
- 通过 Logrus 输出结构化 JSON 日志,保持 `service` 等稳定字段;绝不记录凭据、代理、账号数据、请求体等敏感值。可复用代码只返回错误,并在服务边界记录一次。
- 通过 Logrus 输出结构化 JSON 日志,保持 `service` 等稳定字段。可复用代码只返回错误,并在服务边界记录一次。
- 每个服务只保留一个最小化的 Cobra 根命令。仅当存在真实的运维工作流需求时,才添加子命令、持久化 flag、代码生成器或补全。
- 未经评审的需求批准,不添加 ORM、Redis、任务框架或另一套 HTTP/配置/日志/CLI 技术栈。
+2 -9
View File
@@ -11,14 +11,14 @@
## 本地运行
需要 Docker Compose。控制面仅绑定本机;PostgreSQL 仅在内部 control 网络可见,浏览器网络在阶段 A 默认禁止外网访问:
需要 Docker Compose:
```bash
docker pull git.ipao.vip/rogee/fingerprint-chromium@sha256:b9f23b8e3ac640174db0dfa49e9095fe7eb06f5db55a4e7550d979b35ff3a1b7
DOCKER_GID=$(stat -c %g /var/run/docker.sock) docker compose up --build
```
打开 <http://127.0.0.1:8080>。架构、API 契约、失败语义和 `docker.sock` 风险边界见
打开 <http://127.0.0.1:8080>;局域网内用宿主机 IP 访问同一端口。架构、API 契约、失败语义和 `docker.sock` 风险边界见
[《浏览器容器控制面》](docs/architecture/container-control.md)。
最小验证:
@@ -28,11 +28,4 @@ go test ./...
npm --prefix web ci
npm --prefix web run build
docker compose config --quiet
CREATORHUB_DOCKER_INTEGRATION=1 go test -run TestDockerIntegrationBlocksCrossContainerTraffic ./cmd/docker-gateway
```
## 合规边界
- 自动化行为必须遵守目标平台规则、适用法律和账号授权范围。
- 不实现绕过检测、规避风控或未经授权采集数据的能力。
- 凭据与账号敏感数据不得提交到仓库。
+5 -10
View File
@@ -33,7 +33,6 @@ const (
networkRoleLabel = "io.creatorhub.network-role"
browserNetworkRole = "browser"
controlNetworkName = "creatorhub_control"
bridgeICCOption = "com.docker.network.bridge.enable_icc"
namePrefix = "creatorhub-browser-"
)
@@ -166,7 +165,7 @@ func run(command *cobra.Command, cfg serviceConfig) error {
baseURL: "http://docker/v1.43",
client: &http.Client{Transport: transport, Timeout: 30 * time.Second},
}
if err := docker.ensureInternalNetwork(cfg.network); err != nil {
if err := docker.ensureBrowserNetwork(cfg.network); err != nil {
return err
}
logrus.WithFields(logrus.Fields{
@@ -416,7 +415,7 @@ func (docker dockerClient) expect(method, path string, payload any, allowed ...i
return fmt.Errorf("Docker returned %s: %s", response.Status, strings.TrimSpace(string(message)))
}
func (docker dockerClient) ensureInternalNetwork(name string) error {
func (docker dockerClient) ensureBrowserNetwork(name string) error {
if err := validateBrowserNetwork(name); err != nil {
return err
}
@@ -432,16 +431,14 @@ func (docker dockerClient) ensureInternalNetwork(name string) error {
Internal bool `json:"Internal"`
Attachable bool `json:"Attachable"`
Ingress bool `json:"Ingress"`
Options map[string]string `json:"Options"`
Labels map[string]string `json:"Labels"`
}
if err := json.NewDecoder(response.Body).Decode(&network); err != nil {
return fmt.Errorf("decode browser network: %w", err)
}
if network.Name != name || network.Driver != "bridge" || !network.Internal || network.Attachable || network.Ingress ||
network.Labels[managedLabel] != "true" || network.Labels[networkRoleLabel] != browserNetworkRole ||
len(network.Options) != 1 || network.Options[bridgeICCOption] != "false" {
return fmt.Errorf("browser network %q is not an isolated CreatorHub bridge", name)
if network.Name != name || network.Driver != "bridge" || network.Internal || network.Attachable || network.Ingress ||
network.Labels[managedLabel] != "true" || network.Labels[networkRoleLabel] != browserNetworkRole {
return fmt.Errorf("browser network %q is not a CreatorHub bridge", name)
}
return nil
}
@@ -452,8 +449,6 @@ func (docker dockerClient) ensureInternalNetwork(name string) error {
"Name": name,
"CheckDuplicate": true,
"Driver": "bridge",
"Internal": true,
"Options": map[string]string{bridgeICCOption: "false"},
"Labels": map[string]string{
managedLabel: "true",
networkRoleLabel: browserNetworkRole,
+15 -73
View File
@@ -1,17 +1,11 @@
package main
import (
"context"
"encoding/json"
"fmt"
"net"
"net/http"
"net/http/httptest"
"os"
"os/exec"
"strings"
"testing"
"time"
"github.com/gofiber/fiber/v3"
"github.com/gofiber/fiber/v3/middleware/adaptor"
@@ -236,13 +230,11 @@ func TestGatewayRefusesUnmanagedContainer(t *testing.T) {
}
}
func TestEnsureInternalNetwork(t *testing.T) {
func TestEnsureBrowserNetwork(t *testing.T) {
var created struct {
Name string `json:"Name"`
Driver string `json:"Driver"`
Internal bool `json:"Internal"`
Options map[string]string `json:"Options"`
Labels map[string]string `json:"Labels"`
Name string `json:"Name"`
Driver string `json:"Driver"`
Labels map[string]string `json:"Labels"`
}
docker := httptest.NewServer(http.HandlerFunc(func(response http.ResponseWriter, request *http.Request) {
switch request.Method {
@@ -258,24 +250,22 @@ func TestEnsureInternalNetwork(t *testing.T) {
defer docker.Close()
client := dockerClient{baseURL: docker.URL, client: docker.Client()}
if err := client.ensureInternalNetwork("creatorhub_browser"); err != nil {
if err := client.ensureBrowserNetwork("creatorhub_browser"); err != nil {
t.Fatal(err)
}
if created.Name != "creatorhub_browser" || created.Driver != "bridge" || !created.Internal ||
created.Options[bridgeICCOption] != "false" || len(created.Options) != 1 ||
if created.Name != "creatorhub_browser" || created.Driver != "bridge" ||
created.Labels[managedLabel] != "true" || created.Labels[networkRoleLabel] != browserNetworkRole {
t.Fatalf("network is not isolated: %#v", created)
t.Fatalf("network is not a CreatorHub bridge: %#v", created)
}
}
func TestEnsureInternalNetworkRejectsUnsafeExistingNetwork(t *testing.T) {
func TestEnsureBrowserNetworkRejectsUnsafeExistingNetwork(t *testing.T) {
valid := map[string]any{
"Name": "creatorhub_browser",
"Driver": "bridge",
"Internal": true,
"Internal": false,
"Attachable": false,
"Ingress": false,
"Options": map[string]string{bridgeICCOption: "false"},
"Labels": map[string]string{
managedLabel: "true",
networkRoleLabel: browserNetworkRole,
@@ -286,14 +276,14 @@ func TestEnsureInternalNetworkRejectsUnsafeExistingNetwork(t *testing.T) {
}))
defer validDocker.Close()
client := dockerClient{baseURL: validDocker.URL, client: validDocker.Client()}
if err := client.ensureInternalNetwork("creatorhub_browser"); err != nil {
t.Fatalf("expected owned isolated network to be accepted: %v", err)
if err := client.ensureBrowserNetwork("creatorhub_browser"); err != nil {
t.Fatalf("expected owned bridge network to be accepted: %v", err)
}
tests := map[string]func(map[string]any){
"wrong name": func(network map[string]any) { network["Name"] = "other" },
"wrong driver": func(network map[string]any) { network["Driver"] = "overlay" },
"external": func(network map[string]any) { network["Internal"] = false },
"internal": func(network map[string]any) { network["Internal"] = true },
"attachable": func(network map[string]any) { network["Attachable"] = true },
"ingress": func(network map[string]any) { network["Ingress"] = true },
"missing ownership": func(network map[string]any) {
@@ -302,11 +292,6 @@ func TestEnsureInternalNetworkRejectsUnsafeExistingNetwork(t *testing.T) {
"wrong role": func(network map[string]any) {
network["Labels"] = map[string]string{managedLabel: "true", networkRoleLabel: "control"}
},
"missing ICC": func(network map[string]any) { network["Options"] = map[string]string{} },
"enabled ICC": func(network map[string]any) { network["Options"] = map[string]string{bridgeICCOption: "true"} },
"extra option": func(network map[string]any) {
network["Options"] = map[string]string{bridgeICCOption: "false", "unexpected": "value"}
},
}
for name, mutate := range tests {
@@ -322,20 +307,20 @@ func TestEnsureInternalNetworkRejectsUnsafeExistingNetwork(t *testing.T) {
defer docker.Close()
client := dockerClient{baseURL: docker.URL, client: docker.Client()}
if err := client.ensureInternalNetwork("creatorhub_browser"); err == nil {
if err := client.ensureBrowserNetwork("creatorhub_browser"); err == nil {
t.Fatal("expected unsafe existing network to be rejected")
}
})
}
}
func TestEnsureInternalNetworkRejectsControlNetwork(t *testing.T) {
func TestEnsureBrowserNetworkRejectsControlNetwork(t *testing.T) {
requested := false
docker := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { requested = true }))
defer docker.Close()
client := dockerClient{baseURL: docker.URL, client: docker.Client()}
if err := client.ensureInternalNetwork(controlNetworkName); err == nil || requested {
if err := client.ensureBrowserNetwork(controlNetworkName); err == nil || requested {
t.Fatalf("expected control network to be rejected before Docker request, requested=%v err=%v", requested, err)
}
}
@@ -346,46 +331,3 @@ func TestLoadConfigRejectsControlNetwork(t *testing.T) {
t.Fatal("expected control network configuration to be rejected")
}
}
func TestDockerIntegrationBlocksCrossContainerTraffic(t *testing.T) {
if os.Getenv("CREATORHUB_DOCKER_INTEGRATION") != "1" {
t.Skip("set CREATORHUB_DOCKER_INTEGRATION=1 to run")
}
image := "alpine:3.22@sha256:14358309a308569c32bdc37e2e0e9694be33a9d99e68afb0f5ff33cc1f695dce"
networkName := fmt.Sprintf("creatorhub_test_%d", time.Now().UnixNano())
serverName := networkName + "_server"
runDocker := func(args ...string) ([]byte, error) {
return exec.Command("docker", args...).CombinedOutput()
}
if output, err := runDocker("pull", image); err != nil {
t.Fatalf("pull integration image: %v: %s", err, output)
}
t.Cleanup(func() {
if output, err := runDocker("network", "rm", networkName); err != nil {
t.Logf("remove test network: %v: %s", err, output)
}
})
t.Cleanup(func() {
if output, err := runDocker("rm", "-f", serverName); err != nil {
t.Logf("remove test container: %v: %s", err, output)
}
})
transport := &http.Transport{DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
return (&net.Dialer{}).DialContext(ctx, "unix", "/var/run/docker.sock")
}}
defer transport.CloseIdleConnections()
client := dockerClient{baseURL: "http://docker/v1.43", client: &http.Client{Transport: transport}}
if err := client.ensureInternalNetwork(networkName); err != nil {
t.Fatal(err)
}
if output, err := runDocker("run", "-d", "--name", serverName, "--network", networkName, "--network-alias", "peer", image, "nc", "-lk", "-p", "8080", "-e", "/bin/echo"); err != nil {
t.Fatalf("start peer server: %v: %s", err, output)
}
if output, err := runDocker("exec", serverName, "nc", "-z", "-w", "2", "127.0.0.1", "8080"); err != nil {
t.Fatalf("peer server is not ready: %v: %s", err, output)
}
if output, err := runDocker("run", "--rm", "--network", networkName, image, "nc", "-z", "-w", "2", "peer", "8080"); err == nil {
t.Fatalf("cross-container request unexpectedly succeeded: %s", output)
}
}
+1 -2
View File
@@ -5,7 +5,7 @@ services:
DOCKER_GATEWAY_URL: http://docker-gateway:8081
DATABASE_URL: postgres://creatorhub@postgres/creatorhub?sslmode=disable
ports:
- "127.0.0.1:${CREATORHUB_PORT:-8080}:8080"
- "${CREATORHUB_PORT:-8080}:8080"
read_only: true
tmpfs:
- /tmp:size=16m,noexec,nosuid,nodev
@@ -67,7 +67,6 @@ services:
networks:
control:
name: creatorhub_control
internal: true
volumes:
creatorhub_postgres:
+4 -4
View File
@@ -27,10 +27,10 @@ React ──> control-plane ── /api/browsers ──> docker-gateway ──>
- 镜像、命令、网络、挂载和资源限制均由网关固定,外部输入只有受校验的名称和数字 seed;
- 启停和删除前必须同时匹配固定名称前缀及 `io.creatorhub.managed`、`io.creatorhub.runtime-id` 标签;
- 动态容器使用只读根文件系统、非 root 镜像、全部 capability drop、`no-new-privileges`、CPU/内存/PID 限制,且无宿主机端口和目录挂载;
- 控制面只绑定 `127.0.0.1`,控制网络为固定名称的 Compose internal 网络;浏览器 bridge 关闭 ICC,阻止运行时直接互访,并按 ownership、role、driver、Internal 和完整 options 失败关闭校验,且拒绝复用 control 网络;
- 控制面发布到宿主机所有网卡;控制网络为固定名称的 Compose 网络;浏览器 bridge 按 ownership、role、driver、Internal 失败关闭校验,且拒绝复用 control 网络;
- 浏览器镜像固定为审核过的 immutable digest;运行时创建请求同时固定非 root `1000:1000` 与镜像入口,构建阶段和最终基础镜像也均锁定 digest。
网关自身一旦被攻破,socket 仍允许接管宿主机;应用内校验不能消除这个平台级风险。当前控制面没有认证或 CSRF 防护,只支持可信单用户从 localhost 访问。进入共享或生产环境前,必须先补认证与 CSRF 边界,并把浏览器调度迁到独立 Docker daemon/VM,或使用宿主机 Docker authorization plugin 做第二层强制授权,不应把 socket 暴露给公网服务。
网关自身一旦被攻破,socket 仍允许接管宿主机;应用内校验不能消除这个平台级风险。开发阶段控制面不做认证或访问限制,安全由部署者自行把控。
## 运行
@@ -41,9 +41,9 @@ docker pull git.ipao.vip/rogee/fingerprint-chromium@sha256:b9f23b8e3ac640174db0d
DOCKER_GID=$(stat -c %g /var/run/docker.sock) docker compose up --build
```
打开 <http://127.0.0.1:8080>。浏览器镜像固定为 `git.ipao.vip/rogee/fingerprint-chromium@sha256:b9f23b8e3ac640174db0dfa49e9095fe7eb06f5db55a4e7550d979b35ff3a1b7`。阶段 A 网络默认失败关闭且不能访问外网;后续授权沙箱必须先设计受管出口,再调整 `browser` 网络。
打开 <http://127.0.0.1:8080>,局域网内用宿主机 IP 访问同一端口。浏览器镜像固定为 `git.ipao.vip/rogee/fingerprint-chromium@sha256:b9f23b8e3ac640174db0dfa49e9095fe7eb06f5db55a4e7550d979b35ff3a1b7`。浏览器容器可访问外网。
创建成功但启动失败时,网关会立即删除失败容器并保留命名 Profile 卷,允许同名请求安全重试。跨容器隔离回归可用 `CREATORHUB_DOCKER_INTEGRATION=1 go test -run TestDockerIntegrationBlocksCrossContainerTraffic ./cmd/docker-gateway` 运行。
创建成功但启动失败时,网关会立即删除失败容器并保留命名 Profile 卷,允许同名请求安全重试。
## 阶段 A 离线闭环
+5 -5
View File
@@ -1,6 +1,6 @@
# CreatorHub 部署
本文档适用于当前阶段 A:在一台可信 Linux 主机上通过 Docker Compose 部署,且仅允许本机单用户访问。当前控制面没有认证或 CSRF 防护,PostgreSQL 使用仅限内部网络的 `trust` 认证;不要将服务反向代理到公网或共享网络。
本文档适用于当前阶段 A:在一台 Linux 主机上通过 Docker Compose 部署。开发阶段不设访问限制,安全由部署者自行把控。
## 部署内容
@@ -11,7 +11,7 @@
- `postgres`:PostgreSQL 17,数据保存在 `creatorhub_postgres` 命名卷;
- 浏览器容器:由网关按需创建,使用固定摘要的指纹浏览器镜像,Profile 保存在 `creatorhub-profile-<运行时名称>` 命名卷。
控制面只发布到 `127.0.0.1`。Compose 的 `creatorhub_control` 网络和网关创建的 `creatorhub_browser` 网络均为内部网络;阶段 A 的浏览器容器默认不能访问外网,也不能互相通信。
控制面发布到宿主机所有网卡,局域网内可直接访问;浏览器容器可访问外网。
`creator-hub` 会等待 `docker-gateway` 健康检查通过后再启动。
## 前置条件
@@ -34,7 +34,7 @@ docker compose config --quiet
## 首次部署
以下命令应在同一个 shell、仓库根目录执行。`DOCKER_GID` 必须与宿主机 Docker socket 的组一致;`CREATORHUB_PORT` 仅控制本机监听端口。
以下命令应在同一个 shell、仓库根目录执行。`DOCKER_GID` 必须与宿主机 Docker socket 的组一致;`CREATORHUB_PORT` 控制控制面的宿主机端口。
```bash
export DOCKER_GID="$(stat -c '%g' /var/run/docker.sock)"
@@ -80,7 +80,7 @@ Compose 部署时通常只需设置以下宿主机变量:
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `CREATORHUB_PORT` | `8080` | 映射到 `127.0.0.1` 的控制面端口 |
| `CREATORHUB_PORT` | `8080` | 控制面宿主机端口,局域网可访问 |
| `DOCKER_GID` | `999` | Docker socket 的宿主机组 ID;必须按实际值设置 |
服务本身支持并校验以下环境变量;`compose.yaml` 已提供当前部署所需的值:
@@ -97,7 +97,7 @@ Compose 部署时通常只需设置以下宿主机变量:
| `docker-gateway` | `BROWSER_NETWORK` | `creatorhub_browser` |
| `docker-gateway` | `LOG_LEVEL` | 默认 `info` |
不要把凭据写入仓库或 Compose 文件。共享或生产部署必须先补充认证、CSRF 防护和独立 Docker daemon/VM(或 Docker authorization plugin),并将 PostgreSQL 改为强认证。
不要把凭据写入仓库或 Compose 文件。
## 更新与回滚