From 16995483be875c4a97c92bece51be44cab57ea20 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Fri, 24 Jul 2026 14:35:07 +0800 Subject: [PATCH 1/2] refactor: separate runtime configs from examples --- .gitignore | 5 ++++- Dockerfile | 6 +++--- Makefile | 2 +- {configs => example-configs}/events.yaml | 0 {configs => example-configs}/feishu-bots.yaml | 0 {configs => example-configs}/repos.yaml | 0 {configs => example-configs}/server.yaml | 0 {configs => example-configs}/templates.cn.jsonc | 0 {configs => example-configs}/templates.jsonc | 0 internal/config/config_test.go | 4 ++-- 10 files changed, 10 insertions(+), 7 deletions(-) rename {configs => example-configs}/events.yaml (100%) rename {configs => example-configs}/feishu-bots.yaml (100%) rename {configs => example-configs}/repos.yaml (100%) rename {configs => example-configs}/server.yaml (100%) rename {configs => example-configs}/templates.cn.jsonc (100%) rename {configs => example-configs}/templates.jsonc (100%) diff --git a/.gitignore b/.gitignore index 151e78d..8fff206 100644 --- a/.gitignore +++ b/.gitignore @@ -245,9 +245,12 @@ bin/ logs/* !logs/.gitkeep +# Runtime configuration is initialized from example-configs on first start. +/configs/ + # docker-compose use docker-compose.yml in default, ignore this docker-compose.yaml # OS files .DS_Store -Thumbs.db \ No newline at end of file +Thumbs.db diff --git a/Dockerfile b/Dockerfile index ed00284..0864309 100644 --- a/Dockerfile +++ b/Dockerfile @@ -33,9 +33,9 @@ COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo # Copy the binary COPY --from=builder /build/feishu-github-tracker /app/feishu-github-tracker -# Keep immutable default configuration separate from the writable runtime directory. -COPY --from=builder /build/configs /app/default-configs -ENV DEFAULT_CONFIG_DIR=/app/default-configs +# Keep versioned examples separate from the writable runtime configuration. +COPY --from=builder /build/example-configs /app/example-configs +ENV DEFAULT_CONFIG_DIR=/app/example-configs # Set working directory WORKDIR /app diff --git a/Makefile b/Makefile index 5c81c8f..6a45c04 100644 --- a/Makefile +++ b/Makefile @@ -6,7 +6,7 @@ build: # Run the application locally (with -reload so panel edits apply live) run: - go run ./cmd/feishu-github-tracker -reload + CONFIG_DIR=./configs DEFAULT_CONFIG_DIR=./example-configs LOG_DIR=./logs go run ./cmd/feishu-github-tracker -reload # Run tests test: diff --git a/configs/events.yaml b/example-configs/events.yaml similarity index 100% rename from configs/events.yaml rename to example-configs/events.yaml diff --git a/configs/feishu-bots.yaml b/example-configs/feishu-bots.yaml similarity index 100% rename from configs/feishu-bots.yaml rename to example-configs/feishu-bots.yaml diff --git a/configs/repos.yaml b/example-configs/repos.yaml similarity index 100% rename from configs/repos.yaml rename to example-configs/repos.yaml diff --git a/configs/server.yaml b/example-configs/server.yaml similarity index 100% rename from configs/server.yaml rename to example-configs/server.yaml diff --git a/configs/templates.cn.jsonc b/example-configs/templates.cn.jsonc similarity index 100% rename from configs/templates.cn.jsonc rename to example-configs/templates.cn.jsonc diff --git a/configs/templates.jsonc b/example-configs/templates.jsonc similarity index 100% rename from configs/templates.jsonc rename to example-configs/templates.jsonc diff --git a/internal/config/config_test.go b/internal/config/config_test.go index b8b1631..a607e26 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -175,9 +175,9 @@ feishu_bots: // This test is skipped by default as the real template files are very large and may have formatting issues func TestLoadRealTemplates(t *testing.T) { - // Use real templates from the project's configs directory. + // Use real templates from the project's versioned example-configs directory. // This test requires the files to exist in the repository root. - projectRoot := filepath.Join("..", "..", "configs") + projectRoot := filepath.Join("..", "..", "example-configs") // Ensure templates.jsonc exists templatesPath := filepath.Join(projectRoot, "templates.jsonc") From 99a54a4d514443aa99697034d3d3078853e9fc8e Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Fri, 24 Jul 2026 14:35:08 +0800 Subject: [PATCH 2/2] docs: explain runtime config migration --- README.md | 14 +++++++++----- docs/build-from-source.md | 8 ++++---- docs/quickstart.md | 30 ++++++++++++++++++++++-------- 3 files changed, 35 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 1b5d221..aec1def 100644 --- a/README.md +++ b/README.md @@ -32,9 +32,9 @@ 目前支持所有的 GitHub Webhook 事件 -- 详见 [configs/events.yaml](configs/events.yaml) +- 详见 [example-configs/events.yaml](example-configs/events.yaml) - 对应的处理方法以及文档详见 [internal/handler/](internal/handler/) -- 默认提供的消息模板详见 [configs/templates.jsonc](configs/templates.jsonc) +- 默认提供的消息模板详见 [example-configs/templates.jsonc](example-configs/templates.jsonc) - 也可以自定义模板，使用我们 `handler` 提供的的 `占位符变量` ([详见文档](internal/handler/README.md)) 以及 `template` 提供的 `模板引擎的语法` `过滤器` `条件块` 等功能 ([详见文档](internal/template/README.md)) 对发出消息的格式做相应的修改 ### Webhook 设置提醒 @@ -136,12 +136,13 @@ feishu-github-tracker/ │ └── template/ # 模板处理 ├── pkg/ │ └── logger/ # 日志模块 -├── configs/ # 配置文件目录 +├── example-configs/ # 受 Git 跟踪的默认配置与注释示例 │ ├── server.yaml │ ├── repos.yaml │ ├── events.yaml │ ├── feishu-bots.yaml │ └── templates.jsonc +├── configs/ # 运行时配置目录，首次启动生成且不受 Git 跟踪 ├── logs/ # 日志文件目录 ├── Dockerfile # Docker 镜像构建 ├── docker-compose.yml # Docker Compose 配置 @@ -151,6 +152,8 @@ feishu-github-tracker/ ## 配置说明 +仓库中的 [example-configs](example-configs) 是可随版本更新的默认配置；运行时请编辑 `configs/`。Docker Compose 首次启动会自动从示例目录复制缺失文件，已有文件绝不会被覆盖，因此更新代码不会再因本地配置修改而阻塞。 + ### server.yaml 服务器基础配置： @@ -248,7 +251,7 @@ event_sets: # 包含所有 GitHub 支持的事件... ``` -具体参考 [./configs/events.yaml](./configs/events.yaml) 中的详细内容 +具体参考 [./example-configs/events.yaml](./example-configs/events.yaml) 中的详细内容 ### repos.yaml @@ -450,7 +453,8 @@ make fmt ## 环境变量 -- `CONFIG_DIR` - 配置文件目录路径（默认：`./configs`） +- `CONFIG_DIR` - 运行时配置文件目录路径（Docker 默认：`/app/configs`） +- `DEFAULT_CONFIG_DIR` - 默认配置示例目录；启动时仅复制其中缺失的文件到 `CONFIG_DIR` - `LOG_DIR` - 日志文件目录路径（默认：`./logs`） - `TZ` - 时区设置（默认：`Asia/Shanghai`） diff --git a/docs/build-from-source.md b/docs/build-from-source.md index d9f3265..1e32f49 100644 --- a/docs/build-from-source.md +++ b/docs/build-from-source.md @@ -47,14 +47,14 @@ make docker-up # = docker-compose up -d # 编译 go build -o bin/feishu-github-tracker ./cmd/feishu-github-tracker -# 运行（-reload 启用配置热重载，推荐） -CONFIG_DIR=./configs LOG_DIR=./logs ./bin/feishu-github-tracker -reload +# 运行（首次会从 example-configs 初始化 ./configs；-reload 启用配置热重载） +CONFIG_DIR=./configs DEFAULT_CONFIG_DIR=./example-configs LOG_DIR=./logs ./bin/feishu-github-tracker -reload ``` 或直接 `go run`（等价于 `make run`）： ```bash -go run ./cmd/feishu-github-tracker -reload +CONFIG_DIR=./configs DEFAULT_CONFIG_DIR=./example-configs LOG_DIR=./logs go run ./cmd/feishu-github-tracker -reload ``` `-reload` 会在每次收到 webhook 时重新加载 `./configs/`，修改配置后无需重启即生效。 @@ -71,7 +71,7 @@ docker compose up -d --build go build -o bin/feishu-github-tracker ./cmd/feishu-github-tracker ``` -配置文件位于 `./configs`（挂载卷），升级不会覆盖你已有的配置。 +`./configs` 是本地运行时配置，首次启动由 `./example-configs` 初始化，升级不会覆盖你已有的配置；更新后的示例可直接在 `example-configs/` 中对比。 --- diff --git a/docs/quickstart.md b/docs/quickstart.md index fdde202..ddb926f 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -53,13 +53,13 @@ http://localhost:4594/health ## 4. 修改配置 -编辑 `./configs/` 下的配置文件，参考 [../README.md](../README.md) 或 [../configs](../configs/) 下示例文件的注释。最常需要改的有： +编辑 `./configs/` 下的运行时配置，参考 [../README.md](../README.md) 或 [../example-configs](../example-configs/) 下示例文件的注释。最常需要改的有： -- [../configs/server.yaml](../configs/server.yaml)：监听地址、端口、`secret`（测试可不设） -- [../configs/feishu-bots.yaml](../configs/feishu-bots.yaml)：飞书机器人的 Webhook URL 与别名 +- `./configs/server.yaml`（示例：[server.yaml](../example-configs/server.yaml)）：监听地址、端口、`secret`（测试可不设） +- `./configs/feishu-bots.yaml`（示例：[feishu-bots.yaml](../example-configs/feishu-bots.yaml)）：飞书机器人的 Webhook URL 与别名 - 不清楚「飞书机器人 / Webhook URL」是什么？参考 [飞书文档](https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot)，在群里建一个机器人并复制其 Webhook URL -- [../configs/repos.yaml](../configs/repos.yaml)：要监听的 GitHub 仓库、事件及通知对象 -- [../configs/templates.jsonc](../configs/templates.jsonc)：默认消息模板（可选：创建 `templates.<名称>.jsonc` 自定义模板） +- `./configs/repos.yaml`（示例：[repos.yaml](../example-configs/repos.yaml)）：要监听的 GitHub 仓库、事件及通知对象 +- `./configs/templates.jsonc`（示例：[templates.jsonc](../example-configs/templates.jsonc)）：默认消息模板（可选：创建 `templates.<名称>.jsonc` 自定义模板） 修改后保存，程序会在下一次收到 GitHub Webhook 时自动热重载。 @@ -69,7 +69,7 @@ http://localhost:4594/health - 面板地址：`http://localhost:4594/`（与 webhook 同端口；`/webhook`、`/health` 仍照常工作） - 默认账号：用户名 `admin` / 密码 `admin`（默认配置已带；老版本升级且未配置面板账号时，也自动用 `admin`/`admin`） - - 用户名：可在 [../configs/server.yaml](../configs/server.yaml) 的 `panel.username`、环境变量 `PANEL_USERNAME`，或面板「服务设置」页修改 + - 用户名：可在 `./configs/server.yaml` 的 `panel.username`、环境变量 `PANEL_USERNAME`，或面板「服务设置」页修改 - 密码（优先级从高到低）： - 环境变量（推荐）：`PANEL_PASSWORD=你的密码` - `panel.password`（明文）：**存在则优先使用**；启动 / reload 时会自动转为 `password_hash`（覆盖原 hash）、删除该明文行并补回 `# password: "admin"` 注释 @@ -97,7 +97,7 @@ feishu_bots: - Payload URL：你的服务器地址，如 `http://your-domain-or-ip:4594/webhook` - Content type：选什么都支持 - Secret：填你在 `server.yaml` 配置的 `secret`（如果配了） -- 事件类型：可选 `Let me select individual events` 勾选需要的事件，并在 [../configs/repos.yaml](../configs/repos.yaml) 对应仓库里用 `all:` 等做更细控制；详见 [../configs/events.yaml](../configs/events.yaml) +- 事件类型：可选 `Let me select individual events` 勾选需要的事件，并在 `./configs/repos.yaml` 对应仓库里用 `all:` 等做更细控制；详见 [events.yaml 示例](../example-configs/events.yaml) - 点击 `Add webhook` - ✅ 配置无误的话，几秒后飞书群会收到一条「GitHub Webhook 添加成功」通知（GitHub 发送的 ping 事件），说明 Webhook 已生效 @@ -124,8 +124,22 @@ docker compose up -d # 用新镜像重建容器（本地配置保留） - 新版本引入的新默认配置项，也只在你对应文件缺失时才会自动补入 - 管理面板账号：若你从老版本升级且没配置过面板账号，默认登录 `admin` / `admin`（见 [§5](#5-web-管理面板可选)） +### 从旧版仓库迁移 + +旧版本曾将运行时配置直接纳入 Git 跟踪。首次拉取本次目录迁移前，请先备份并暂存本地配置，避免 Git 因配置文件修改拒绝更新： + +```bash +cp -a configs ../feishu-github-tracker-configs-backup +git stash push -m "backup runtime configs before config split" -- configs +git pull +mkdir -p configs +cp -a ../feishu-github-tracker-configs-backup/. configs/ +``` + +迁移后 `configs/` 已被忽略；以后更新时可直接比较 `example-configs/` 与本地 `configs/`，不会再产生配置文件的 Git 修改。 + > 从源码部署的更新方式见 [从源码构建 · 更新源码版本](build-from-source.md#更新源码版本)。 --- -更多配置与高级用法见 [../README.md](../README.md)、[../configs](../configs/) 示例注释，或 [../internal/handler](../internal/handler/)、[../internal/template](../internal/template/) 下的文档。 +更多配置与高级用法见 [../README.md](../README.md)、[../example-configs](../example-configs/) 示例注释，或 [../internal/handler](../internal/handler/)、[../internal/template](../internal/template/) 下的文档。