From 803362bbc74e9d96a18eb55be842c9d914dc7ff2 Mon Sep 17 00:00:00 2001
From: OpenClaw Agent <openclaw@example.com>
Date: Wed, 16 Sep 2026 07:03:32 +0800
Subject: [PATCH] docs: add deployment and sanitized configuration

---
 .dockerignore |  8 ++++--
 .env.example  |  6 +++++
 .gitignore    |  6 +++++
 README.md     | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 93 insertions(+), 2 deletions(-)
 create mode 100644 .env.example
 create mode 100644 README.md

diff --git a/.dockerignore b/.dockerignore
index a64173b..b1cc6e6 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -2,6 +2,10 @@
 .gitignore
 data
 downloads
-*.pre-*
-*.backup-*
+*.db
+*.db-*
 *.log
+.env
+.env.*
+*.part
+legacy
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..8a50646
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,6 @@
+# Optional deployment overrides. Do not put real credentials here.
+PORT=9540
+DB_PATH=/data/downloader.db
+DOWNLOAD_DIR=/downloads
+AM_API_URL=http://127.0.0.1:9530/api
+WORKERS=2
diff --git a/.gitignore b/.gitignore
index 6c7abbb..66383ac 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,9 @@
 data/
 downloads/
 *.db
+*.db-*
+*.log
+.env
+.env.*
+*.part
+legacy/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5160a43
--- /dev/null
+++ b/README.md
@@ -0,0 +1,75 @@
+# AM Downloader
+
+独立的音乐搜索与下载 Web 服务，使用 AM 音乐 API 解析资源，并可选同步到 WebDAV/NAS。
+
+## 特性
+
+- 音乐搜索与分页
+- 下载队列、去重、失败重试
+- 自动识别实际音频格式，避免错误扩展名
+- 标记解析后的音质与实际音质
+- WebDAV/NAS 同步
+- 可配置同曲低音质版本清理策略
+- 可配置上传成功后的本地文件清理策略
+- Docker Compose 部署
+
+## 架构
+
+`9540` 提供 Downloader Web/API；音乐解析服务通过配置的 `AM_API_URL` 访问，默认指向本机 `9530`。
+
+运行时数据库和下载文件不会进入 Git 仓库。
+
+## 快速部署
+
+```bash
+git clone <your-gitea-repository>
+cd am-downloader
+docker compose up -d --build
+```
+
+默认访问：`http://127.0.0.1:9540`
+
+## 配置
+
+Docker Compose 中只保存非敏感的运行参数。WebDAV 凭据通过 Web UI 的设置页面写入运行时数据库，**不要将数据库提交到 Git**。
+
+可配置：
+
+- `PORT`：Web 服务端口，默认 `9540`
+- `DB_PATH`：SQLite 数据库路径
+- `DOWNLOAD_DIR`：下载目录
+- `AM_API_URL`：AM 音乐 API 地址
+- `WORKERS`：下载 worker 数量
+
+首次部署后进入设置页面填写 WebDAV 地址、用户名、密码和远程目录。
+
+## 数据与安全
+
+以下内容属于运行时数据，默认被 `.gitignore` 排除：
+
+- `data/`
+- `downloads/`
+- `*.db`
+- 日志、临时文件和本地环境文件
+
+提交前应检查 Git diff，确认没有密码、Token、Cookie、私有密钥或个人环境配置。
+
+## 开发
+
+```bash
+go test ./...
+go build -o am-downloader .
+```
+
+前端为单页静态界面，由 Go 服务直接提供。
+
+## API
+
+- `GET /api/search`
+- `GET /api/tasks`
+- `POST /api/tasks`
+- `POST /api/tasks/:id/retry`
+- `DELETE /api/tasks/:id`
+- `GET /api/settings`
+- `PUT /api/settings`
+- `POST /api/webdav/test`