OpenFlare/docs/plan/20260606-replace-import-paths-evaluation.md

OpenFlare 引用替换为 GitHub 路径方案评估计划

1. 目标与背景 (Goal & Context)

• 需求背景：当前 OpenFlare 内部组件（Server、Agent、Relay、Flared）之间采用本地包名引用（例如 openflare、openflare-agent），并使用 Go replace 相对路径指向本地目录。这导致代码无法直接以标准的 GitHub 路径（如 github.com/rain-kl/openflare）进行分发、远程安装或被外部引用（例如 go install 远程二进制会因为 replace 指令失效而报错）。
• 评估目标：评估将本地引用替换为 github.com/rain-kl/openflare 格式的两种可行方案（单模块 Monorepo 方案 vs 多模块 Multi-Module 方案），分析各自的优缺点、工作量及对现有 CI/CD、Docker 镜像构建的影响，给出推荐方案。

2. 设计与决策 (Design & Decisions)

方案 A：标准 Go 多模块方案 (Multi-Module with Sub-paths)

保留当前 4 个独立的 Go 模块结构，在各自的 go.mod 中将模块名改写为符合 GitHub 结构的子路径：

• openflare-server/go.mod -> module github.com/rain-kl/openflare/openflare-server
• openflare-relay/go.mod -> module github.com/rain-kl/openflare/openflare-relay
• openflare-agent/go.mod -> module github.com/rain-kl/openflare/openflare-agent
• openflared/go.mod -> module github.com/rain-kl/openflare/openflared

同时，其他模块（Relay, Agent, Flared）的 go.mod 中的 replace 修改为： replace github.com/rain-kl/openflare/openflare-server => ../openflare-server

优缺点分析：

• 优点：
  • 模块边界清晰：各二进制模块依赖独立。例如 openflare-agent 不会引入 Server 依赖的 GORM、Gin、Swagger 等库，保持各自模块的 go.sum 纯净。
  • 改动小：对 Dockerfile 和 GitHub Workflows 影响极小，构建上下文仍可保持原样。
• 缺点：
  • 远程安装不可用：仍然需要在 go.mod 中保留 replace 指令。由于 Go 不允许在远程 go install 或 go get 时解析本地相对路径的 replace 指令，用户依然无法直接通过 go install github.com/rain-kl/openflare/openflared/cmd/flared@latest 安装，必须先克隆整个仓库到本地再构建。

---

方案 B：统一单模块方案 (Unified Single Module Monorepo - 推荐)

将整个仓库合并为一个 Go 模块。在仓库根目录下创建 go.mod，模块名为 github.com/rain-kl/openflare，并删除子目录中的所有 go.mod 和 go.sum。

所有内部包导入路径统一改写为：

• "github.com/rain-kl/openflare/openflare-server/..."
• "github.com/rain-kl/openflare/openflare-relay/..."
• "github.com/rain-kl/openflare/openflare-agent/..."
• "github.com/rain-kl/openflare/openflared/..."

优缺点分析：

• 优点：
  • 彻底摆脱 replace：完全不需要在 go.mod 中写 replace 指令，代码清爽、易于维持。
  • 支持远程 Go 工具链：用户和开发者可以直接使用 go install github.com/rain-kl/openflare/openflared/cmd/flared@latest 或 go install github.com/rain-kl/openflare/openflare-agent/cmd/agent@latest 远程下载并安装最新二进制。
  • 版本依赖统一：所有组件共享相同的依赖版本，避免了组件间因第三方库版本不一致导致潜在的运行时兼容问题。
• 缺点：
  • 依赖库大一统：根目录的 go.mod 会包含 Server、Agent、Relay 等所有组件的依赖，但这只影响开发时的依赖下载，对最终编译出的二进制大小和运行效率没有任何影响（Go 编译器会自动进行死代码消除/树摇）。
  • 构建配置变动：Dockerfile 以及 GitHub Actions 需要修改构建上下文，从原本 COPY 子目录改为从根目录统一进行 COPY 和 go build。

---

3. 具体修改文件清单 (Proposed Changes)

如果采用方案 B（推荐），需要修改的文件清单和逻辑如下：

根目录与配置文件

• [NEW] go.mod

  • 职责：全局单一 Go 模块定义，模块名：github.com/rain-kl/openflare。

• [DELETE] openflare-server/go.mod / go.sum

• [DELETE] openflare-relay/go.mod / go.sum

• [DELETE] openflare-agent/go.mod / go.sum

• [DELETE] openflared/go.mod / go.sum

源代码文件 (约 252 个 Go 文件)

• [MODIFY] openflare-server/**/*.go

  • 职责：将 import "openflare/..." 替换为 import "github.com/rain-kl/openflare/openflare-server/..."。

• [MODIFY] openflare-relay/**/*.go

  • 职责：将 import "openflare-relay/..." 替换为 import "github.com/rain-kl/openflare/openflare-relay/..."，将 import "openflare/..." 替换为 import "github.com/rain-kl/openflare/openflare-server/..."。

• [MODIFY] openflare-agent/**/*.go

  • 职责：将 import "openflare-agent/..." 替换为 import "github.com/rain-kl/openflare/openflare-agent/..."，将 import "openflare/..." 替换为 import "github.com/rain-kl/openflare/openflare-server/..."。

• [MODIFY] openflared/**/*.go

  • 职责：将 import "openflare-flared/..." 替换为 import "github.com/rain-kl/openflare/openflared/..."，将 import "openflare/..." 替换为 import "github.com/rain-kl/openflare/openflare-server/..."。

Dockerfile & Workflows

如果采用方案 B（推荐），我们将继续保持每个组件（Server、Agent、Relay、Flared）编译并产生自己独立的 Docker 镜像（共 4 个镜像），但其 Dockerfile 的构建上下文（Build Context）统一提升至仓库根目录。具体调整细节如下：

• [MODIFY] openflare-server/Dockerfile

  • 职责：由于 openflare-server 中没有独立的 go.mod，构建上下文必须在仓库根目录执行。
  • 修改内容：

    # 更改 go-builder 阶段的 COPY 方式：
    COPY go.mod go.sum ./
    RUN go mod download
    COPY openflare-server/ ./openflare-server/
    # go build 指定编译子包：
    RUN go build -trimpath -ldflags "-s -w -X 'github.com/rain-kl/openflare/openflare-server/common.Version=$VERSION'" -o openflare ./openflare-server
    

• [MODIFY] openflare-relay/Dockerfile

  • 职责：适配单 go.mod 构建上下文。
  • 修改内容：

    # 更改 builder 阶段的 COPY 方式：
    COPY go.mod go.sum ./
    RUN go mod download
    COPY openflare-server/ ./openflare-server/
    COPY openflare-relay/ ./openflare-relay/
    # go build 指定编译子包：
    RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "-s -w -X 'github.com/rain-kl/openflare/openflare-relay/internal/config.Version=$VERSION'" -o openflare-relay ./openflare-relay/cmd/relay
    

• [MODIFY] openflare-agent/Dockerfile

  • 职责：适配单 go.mod 构建上下文。
  • 修改内容：

    # 更改 builder 阶段的 COPY 方式：
    COPY go.mod go.sum ./
    RUN go mod download
    COPY openflare-server/ ./openflare-server/
    COPY openflare-agent/ ./openflare-agent/
    # go build 指定编译子包：
    RUN go build -trimpath -ldflags "-s -w -X 'github.com/rain-kl/openflare/openflare-agent/internal/config.Version=$VERSION'" -o /build/openflare-agent ./openflare-agent/cmd/agent
    

• [MODIFY] openflared/Dockerfile

  • 职责：适配单 go.mod 构建上下文。
  • 修改内容：

    # 更改 builder 阶段的 COPY 方式：
    COPY go.mod go.sum ./
    RUN go mod download
    COPY openflare-server/ ./openflare-server/
    COPY openflared/ ./openflared/
    # go build 指定编译子包：
    RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "-s -w -X 'github.com/rain-kl/openflare/openflared/internal/config.Version=$VERSION'" -o flared ./openflared/cmd/flared
    

• [MODIFY] .github/workflows/release.yml

  • 职责：更新 go build 构建命令及 ldflags 版本注入参数（例如将 -ldflags "-X 'openflare/common.Version=$VERSION'" 替换为 -ldflags "-X 'github.com/rain-kl/openflare/openflare-server/common.Version=$VERSION'"，同时编译命令需要指向正确的子包目录，如 ./openflare-server）。

---

4. 验证计划 (Verification Plan)

编译与运行测试

• 运行单测以确保各包逻辑正常： go test ./...（在根目录执行）
• 本地编译各个二进制： go build -o bin/openflare-server ./openflare-server go build -o bin/openflare-agent ./openflare-agent/cmd/agent go build -o bin/openflare-relay ./openflare-relay/cmd/relay go build -o bin/openflared ./openflared/cmd/flared
• 启动服务并检查版本输出： ./bin/openflare-server --version

Docker 构建验证

• 验证镜像构建命令： docker build -t openflare-server -f openflare-server/Dockerfile . docker build -t openflare-agent -f openflare-agent/Dockerfile . docker build -t openflare-relay -f openflare-relay/Dockerfile . docker build -t openflared -f openflared/Dockerfile .