From bb70f3432d12a22f816d1a4b99fa39ce63ffab46 Mon Sep 17 00:00:00 2001
From: yyc12345 <yyc12321@outlook.com>
Date: Fri, 17 Jul 2026 16:44:57 +0800
Subject: [PATCH] doc: add readme and config toml example for new backend

---
 assets/coconut-leaf.template.toml | 23 ++++++++++
 backend/README.md                 | 70 +++++++++++++++++++++++++++++++
 2 files changed, 93 insertions(+)
 create mode 100644 assets/coconut-leaf.template.toml
 create mode 100644 backend/README.md

diff --git a/assets/coconut-leaf.template.toml b/assets/coconut-leaf.template.toml
new file mode 100644
index 0000000..d9d95ff
--- /dev/null
+++ b/assets/coconut-leaf.template.toml
@@ -0,0 +1,23 @@
+[database]
+driver = "sqlite"
+
+[database.config]
+path = "coconut-leaf.db"
+
+# MySQL（占位，尚未实现）
+# [database]
+# driver = "mysql"
+#
+# [database.config]
+# host = "localhost"
+# port = 3306
+# user = "root"
+# password = "password"
+# database = "coconut_leaf"
+
+[web]
+port = 8848
+
+[others]
+auto-token-clean-duration = 86400   # 自动清理过期 token 的间隔（秒）
+debug = true                        # 开启后日志级别降到 DEBUG
diff --git a/backend/README.md b/backend/README.md
new file mode 100644
index 0000000..0803d64
--- /dev/null
+++ b/backend/README.md
@@ -0,0 +1,70 @@
+# coconut-leaf 后端
+
+coconut-leaf 的后端服务，使用 [Go](https://go.dev/) + [Gin](https://gin-gonic.com/) 实现，由旧版 Python Flask 后端迁移而来。
+数据层直接执行 SQL（不使用 ORM），目前仅完整实现 SQLite，MySQL 接口为占位实现（全部接口返回 not implemented 错误）。
+
+## 环境要求
+
+- **Go >= 1.26**
+- **C 编译器（cgo）**：SQLite 驱动 [`mattn/go-sqlite3`](https://github.com/mattn/go-sqlite3) 依赖 cgo。
+  - Windows：推荐使用 MSYS2 的 gcc。
+  - Linux / macOS：系统自带的 gcc / clang 即可。
+- 构建前确保 `CGO_ENABLED=1`（有可用 C 编译器时通常默认开启）。
+
+## 构建
+
+在 `backend/` 目录下：
+
+```sh
+go build -o coconut-leaf
+```
+
+> [!NOTE]
+> 首次构建会编译 SQLite 的 C 源，耗时 1–3 分钟属正常。
+> 
+> 在 Windows 下用 MSYS2 编译出的可执行文件在运行时依赖 MSYS2 相关运行库（我这里是MSYS2 UCRT64，所以可能包含 `libgcc_s_*`、`libwinpthread-1.dll` 等）。
+> 需让这些DLL所在文件夹处于 PATH 中，或将这些 DLL 拷贝到可执行文件旁。
+
+## 配置文件
+
+采用 TOML 格式，通过 `--config` 指定路径。完整模板见 `assets` 文件夹下的 [coconut-leaf.template.toml](../assets/coconut-leaf.template.toml)。
+
+字段说明：
+
+| 字段 | 含义 |
+| --- | --- |
+| `database.driver` | `"sqlite"` 或 `"mysql"` |
+| `database.config.path` | SQLite 数据库文件路径 |
+| `database.config.{host,port,user,password,database}` | MySQL 连接参数（未实现） |
+| `web.port` | HTTP 监听端口 |
+| `others.debug` | 调试模式（生产环境请务必设置为false） |
+| `others.auto-token-clean-duration` | 过期 token 自动清理间隔（秒） |
+
+## 命令行参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `--config <PATH>` | **必填**，配置文件（TOML）路径 |
+| `--init` | 初始化系统：建表并创建首个管理员用户 |
+| `--username <NAME>` | 与 `--init` 配合，初始管理员的用户名 |
+| `--password <PASS>` | 与 `--init` 配合，初始管理员的密码 |
+
+`--username` / `--password` 仅在 `--init` 时必填，并会做格式校验（用户名为 `[0-9A-Za-z]+`，密码为所有可见 ASCII 字符，即 `[!-~]+`）。
+
+## 初始化与运行
+
+### 首次部署
+
+首次部署包括：建表 + 创建管理员，随后如日常运行一般：
+
+```sh
+./coconut-leaf --config coconut-leaf.toml --init --username admin --password "your-password"
+```
+
+### 日常运行
+
+```sh
+./coconut-leaf --config coconut-leaf.toml
+```
+
+启动后会在 `web.port` 监听。调试日志会输出到 stderr，格式为 `[<时间>] [<级别>] <消息> [key=value ...]`。