Separate runtime and example config

.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
+Thumbs.db

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

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:

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`）
 

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/` 中对比。
 
 ---
 

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/) 下的文档。

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")