feat: 初始提交

2026-05-26 18:19:42 +08:00
commit 7ebf5ee5dc
107 changed files with 9317 additions and 0 deletions
--- a/docs/user/config.md
+++ b/docs/user/config.md
@@ -0,0 +1,106 @@
+# 配置文件
+
+项目使用 YAML 配置文件，配置文件为启动时的必传参数，支持通过 JSON Schema 编辑器提示和显式变量引用。配置中的相对路径均基于配置文件所在目录解析，绝对路径保持不变。
+
+## 配置文件
+
+复制 config.example.yaml 为 config.yaml（或任意名称），根据需要修改：
+
+```yaml
+# yaml-language-server: $schema=./config.schema.json
+server:
+  listen:
+    host: "127.0.0.1"
+    port: 3000
+  storage:
+    dataDir: ./data
+  logging:
+    level: info
+    console:
+      level: info
+    file:
+      level: info
+      path: "./logs/my-app.log"
+      rotation:
+        size: 50MB
+        frequency: daily
+        maxFiles: 14
+```
+
+## server.listen
+
+| 字段 | 类型   | 说明                     |
+| ---- | ------ | ------------------------ |
+| host | string | 监听地址，默认 127.0.0.1 |
+| port | number | 监听端口，默认 3000      |
+
+## server.storage
+
+| 字段    | 类型   | 说明                                                |
+| ------- | ------ | --------------------------------------------------- |
+| dataDir | string | 数据目录，默认 ./data，相对路径基于配置文件目录解析 |
+
+## server.logging
+
+| 字段  | 类型   | 说明                                                         |
+| ----- | ------ | ------------------------------------------------------------ |
+| level | string | 全局日志级别（trace/debug/info/warn/error/fatal），默认 info |
+
+### server.logging.console
+
+| 字段  | 类型   | 说明                                              |
+| ----- | ------ | ------------------------------------------------- |
+| level | string | 控制台日志级别，未设置时继承 server.logging.level |
+
+### server.logging.file
+
+| 字段  | 类型   | 说明                                            |
+| ----- | ------ | ----------------------------------------------- |
+| level | string | 文件日志级别，未设置时继承 server.logging.level |
+| path  | string | 日志文件路径，默认 <dataDir>/logs/my-app.log    |
+
+### server.logging.file.rotation
+
+| 字段      | 类型   | 说明                                          |
+| --------- | ------ | --------------------------------------------- |
+| size      | string | 按大小轮转，支持 B/KB/MB/GB 单位，默认 50MB   |
+| frequency | string | 按时间轮转（hourly/daily/weekly），默认 daily |
+| maxFiles  | number | 最大归档文件数，默认 14                       |
+
+## JSON Schema
+
+根目录 config.schema.json 为配置文件的 JSON Schema，支持 IDE 自动补全和校验。
+
+```bash
+bun run schema        # 重新生成 config.schema.json
+bun run schema:check  # 校验 config.schema.json 是否同步
+```
+
+## 变量语法
+
+YAML 配置中支持显式变量引用：
+
+```text
+${KEY}        引用变量，未定义时报错
+${KEY|value}  引用变量，未定义时使用默认值
+${KEY|}       引用变量，未定义时使用空字符串
+$${KEY}       转义，输出 ${KEY} 原文字面量
+```
+
+变量解析优先级：variables 字段 > process.env > 默认值 > unresolved 报错
+
+完整变量引用（整个值只有 ${...}）保留原始类型：${PORT|3000} 解析为 number 3000。部分拼接统一转为 string。
+
+## 配置优先级
+
+```
+variables 字段 > 环境变量 > 默认值 > unresolved 报错
+```
+
+环境变量不会隐式覆盖配置，只有通过 ${KEY} 显式引用时才生效。
+
+## 使用自定义配置
+
+```bash
+bun run dev custom-config.yaml
+```