commit 9af15b987563953a69a493a6e82691e0dbc3e837
Author: diexi <393287649@qq.com>
Date:   Wed Sep 23 09:19:35 2026 +0800

    添加 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e91a366
--- /dev/null
+++ b/README.md
@@ -0,0 +1,305 @@
+# 吾域服务器(nestify)
+
+吾域服务器(nestify)是一个面向个人与家庭使用的私有云服务端，将网盘、Markdown 笔记、远程图库、WebDAV 和多用户管理整合为一个可执行程序。Web 管理界面已经嵌入服务端，无需单独安装 Web 服务器或 Node.js。
+
+## 功能
+
+- 多用户注册与登录，首个注册用户自动成为管理员
+- 管理员与普通用户角色、账户启用和禁用
+- 用户文件、笔记、媒体索引和 WebDAV 数据相互隔离
+- Markdown 笔记创建、编辑、删除与全文搜索
+- 文件夹浏览、上传、下载、删除和新建目录
+- 可恢复分片上传、弱网络重试和取消清理
+- 图片图库、视频缩略图和支持拖动进度的流媒体播放
+- WebDAV，可连接系统文件管理器及兼容客户端
+- Web 管理界面和 HarmonyOS 客户端 API
+- 邮箱密码找回、登录限流和会话失效控制
+
+## 下载正确的版本
+
+| 运行设备 | 下载文件 |
+| :--- | :--- |
+| 常见 Intel/AMD 处理器 Linux | `nestify-<版本>-linux-amd64.tar.gz` |
+| ARM64 Linux、部分 NAS 或开发板 | `nestify-<版本>-linux-arm64.tar.gz` |
+| 常见 Intel/AMD 处理器 Windows | `nestify-<版本>-windows-amd64.zip` |
+| ARM64 Windows | `nestify-<版本>-windows-arm64.zip` |
+
+不确定 Windows 架构时，通常选择 `windows-amd64`。不确定 Linux 架构时可执行 `uname -m`：`x86_64` 选择 `amd64`，`aarch64` 或 `arm64` 选择 `arm64`。
+
+下载后可使用发布页中的 `SHA256SUMS` 校验文件完整性。
+
+Linux：
+
+```bash
+sha256sum -c SHA256SUMS
+```
+
+Windows PowerShell：
+
+```powershell
+Get-FileHash .\nestify-v1.0.0-windows-amd64.zip -Algorithm SHA256
+```
+
+将 PowerShell 输出与 `SHA256SUMS` 中对应文件的值比较。只要所下载归档的校验结果一致即可，缺少其他平台归档导致的提示可以忽略。
+
+## 运行要求
+
+- 可执行文件本身无需安装 Go、Node.js、Docker 或数据库服务。
+- 默认监听 TCP `8080` 端口。
+- 服务端必须对数据目录具有读写权限。
+- 视频缩略图需要目标系统已安装 `ffmpeg`；未安装时普通文件、笔记及图片功能仍可使用。
+- 公网部署强烈建议使用 Caddy、Nginx 等反向代理提供 HTTPS。
+
+## 必需配置
+
+吾域服务器(nestify)通过环境变量读取配置。压缩包中的 `.env.example` 只是配置示例，程序不会自动读取该文件。
+
+完整配置项如下；生产环境至少应设置环境、数据目录、JWT 密钥和实际外部访问地址：
+
+| 环境变量 | 默认值 | 说明 |
+| :--- | :--- | :--- |
+| `NESTIFY_ENV` | `development` | 设为 `production` 后启用生产模式和安全 Cookie |
+| `NESTIFY_PORT` | `8080` | HTTP 监听端口 |
+| `NESTIFY_DATA_DIR` | `./data` | 数据根目录，长期运行建议使用绝对路径 |
+| `NESTIFY_DB_PATH` | `<数据目录>/nestify.db` | SQLite 数据库文件路径，通常无需单独设置 |
+| `NESTIFY_JWT_SECRET` | `change-me-in-production` | JWT 签名密钥；生产模式使用默认值时服务会拒绝启动 |
+| `NESTIFY_REGISTRATION_MODE` | `closed` | `closed` 仅允许创建首个管理员，`open` 允许后续公开注册 |
+| `NESTIFY_PUBLIC_URL` | `http://localhost:8080` | 密码重置邮件中的外部 Web 地址，不要保留无法远程访问的 localhost |
+| `NESTIFY_SMTP_HOST` | 空 | SMTP 服务器；为空时不发送密码重置邮件 |
+| `NESTIFY_SMTP_PORT` | `587` | SMTP STARTTLS 端口 |
+| `NESTIFY_SMTP_USERNAME` | 空 | SMTP 用户名 |
+| `NESTIFY_SMTP_PASSWORD` | 空 | SMTP 密码或授权码 |
+| `NESTIFY_SMTP_FROM` | 空 | 发件人邮箱 |
+
+可使用以下命令生成 JWT 密钥：
+
+```bash
+openssl rand -hex 32
+```
+
+请长期保存同一个密钥。修改密钥会使所有现有登录会话失效。
+
+## Linux 部署
+
+### 1. 解压
+
+```bash
+tar -xzf nestify-v1.0.0-linux-amd64.tar.gz
+cd nestify-v1.0.0-linux-amd64
+chmod +x nestify
+```
+
+ARM64 设备请替换为对应的 `linux-arm64` 文件。
+
+### 2. 首次前台运行
+
+```bash
+export NESTIFY_ENV=production
+export NESTIFY_PORT=8080
+export NESTIFY_DATA_DIR="$PWD/data"
+export NESTIFY_JWT_SECRET="替换为随机密钥"
+export NESTIFY_REGISTRATION_MODE=closed
+export NESTIFY_PUBLIC_URL="http://服务器地址:8080"
+./nestify
+```
+
+浏览器访问 `http://服务器地址:8080`。空数据库中的第一个注册用户会自动成为管理员；完成注册后，默认不允许其他用户自行注册。
+
+### 3. 使用 systemd 长期运行
+
+建议将程序放在 `/opt/nestify`，数据放在 `/var/lib/nestify`：
+
+```bash
+sudo mkdir -p /opt/nestify /var/lib/nestify
+sudo cp nestify /opt/nestify/
+sudo useradd --system --home /var/lib/nestify --shell /usr/sbin/nologin nestify 2>/dev/null || true
+sudo chown -R nestify:nestify /opt/nestify /var/lib/nestify
+```
+
+创建 `/etc/nestify.env`：
+
+```ini
+NESTIFY_ENV=production
+NESTIFY_PORT=8080
+NESTIFY_DATA_DIR=/var/lib/nestify
+NESTIFY_JWT_SECRET=替换为随机密钥
+NESTIFY_REGISTRATION_MODE=closed
+NESTIFY_PUBLIC_URL=https://cloud.example.com
+```
+
+保护配置文件：
+
+```bash
+sudo chmod 600 /etc/nestify.env
+```
+
+创建 `/etc/systemd/system/nestify.service`：
+
+```ini
+[Unit]
+Description=吾域服务器(nestify)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=nestify
+Group=nestify
+WorkingDirectory=/var/lib/nestify
+EnvironmentFile=/etc/nestify.env
+ExecStart=/opt/nestify/nestify
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+启动服务：
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now nestify
+sudo systemctl status nestify
+```
+
+查看日志：
+
+```bash
+journalctl -u nestify -f
+```
+
+## Windows 部署
+
+### 1. 解压
+
+将 ZIP 解压到固定目录，例如：
+
+```text
+C:\Nestify
+```
+
+建议将数据放在：
+
+```text
+C:\Nestify\data
+```
+
+### 2. 使用 PowerShell 运行
+
+```powershell
+Set-Location C:\Nestify
+$env:NESTIFY_ENV = 'production'
+$env:NESTIFY_PORT = '8080'
+$env:NESTIFY_DATA_DIR = 'C:\Nestify\data'
+$env:NESTIFY_JWT_SECRET = '替换为随机密钥'
+$env:NESTIFY_REGISTRATION_MODE = 'closed'
+$env:NESTIFY_PUBLIC_URL = 'http://服务器地址:8080'
+.\nestify.exe
+```
+
+这些变量只对当前 PowerShell 进程有效，不会修改系统环境。浏览器访问 `http://服务器地址:8080` 完成首个管理员注册。
+
+Windows 防火墙若阻止访问，需要为 TCP `8080` 创建入站规则，或仅允许反向代理访问该端口。
+
+### 3. 长期后台运行
+
+Windows 长期运行建议使用 WinSW、NSSM 等服务包装器，将 `C:\Nestify\nestify.exe` 注册为 Windows 服务，并设置：
+
+- 工作目录：`C:\Nestify`
+- 启动类型：自动
+- 上述 `NESTIFY_*` 环境变量
+- 服务账户对 `C:\Nestify\data` 的读写权限
+
+服务包装器不是吾域服务器(nestify)发布包的一部分，请从其官方渠道下载。也可以创建 PowerShell 启动脚本，并通过 Windows 任务计划程序设置为开机启动。
+
+## 邮件密码找回
+
+如需使用“忘记密码”，请配置上表中的全部 SMTP 项，并确保 `NESTIFY_PUBLIC_URL` 是用户可以访问的 HTTPS 地址。未配置 SMTP 时，其余服务不受影响，但无法发送密码重置邮件。
+
+## WebDAV
+
+服务启动后，WebDAV 地址为：
+
+```text
+http://服务器地址:8080/webdav/
+```
+
+使用吾域服务器(nestify)的用户名和密码进行 Basic Auth 登录。每个用户只能访问自己的文件区。账户被管理员禁用或密码被重置后，原有 WebDAV 凭据立即失效。
+
+公网使用 WebDAV 时必须配置 HTTPS。部分 Windows 客户端对明文 HTTP WebDAV 有额外限制。
+
+## 反向代理与 HTTPS
+
+建议让吾域服务器(nestify)仅监听内网端口，由 Caddy 或 Nginx 对外提供 HTTPS。反向代理必须支持：
+
+- 普通 HTTP API 请求
+- 大文件上传
+- WebDAV 方法
+- 视频 Range 请求
+- 较长的上传和下载超时
+
+启用 HTTPS 后，将 `NESTIFY_PUBLIC_URL` 设置为完整外部地址，例如 `https://cloud.example.com`。
+
+## 数据与备份
+
+默认情况下，所有持久化数据都位于 `NESTIFY_DATA_DIR`：
+
+```text
+data/
+├── nestify.db
+├── files/
+├── notes/
+└── cache/
+```
+
+备份时建议：
+
+1. 停止吾域服务器(nestify)服务。
+2. 完整复制整个数据目录，而不仅是数据库文件；如单独设置了 `NESTIFY_DB_PATH`，还要备份该数据库文件。
+3. 备份 JWT 密钥及服务配置，但不要公开其中的密码。
+4. 重新启动服务。
+
+`cache/` 可以重新生成，但保留它可避免重新创建媒体缩略图。
+
+## 升级
+
+1. 下载与当前系统和架构匹配的新版本。
+2. 备份完整数据目录和配置。
+3. 停止吾域服务器(nestify)。
+4. 仅替换可执行文件，不要删除数据目录。
+5. 重新启动并检查日志及 Web 页面。
+
+服务启动时会自动执行必要的数据库迁移。升级后如需回退，应恢复升级前的数据备份和旧版可执行文件。
+
+## 常见问题
+
+### 服务提示 JWT 密钥无效
+
+生产模式不允许默认密钥。请设置一个随机的 `NESTIFY_JWT_SECRET` 后重新启动。
+
+### 其他设备无法访问
+
+检查服务器 IP、TCP 端口、防火墙和路由器策略。移动设备不能使用服务器自身的 `localhost` 地址。
+
+### 视频没有缩略图
+
+确认服务器已安装 FFmpeg，并且运行吾域服务器(nestify)的账户可以执行 `ffmpeg`。
+
+### 注册入口不可用
+
+空数据库始终允许创建首个管理员。创建后，`NESTIFY_REGISTRATION_MODE=closed` 会关闭公开注册；需要开放时改为 `open` 并重启。
+
+### 忘记管理员密码且未配置 SMTP
+
+当前没有绕过认证的管理员重置接口。请在部署前配置 SMTP，并妥善保存管理员密码和数据备份。
+
+## 安全建议
+
+- 公网部署必须使用 HTTPS。
+- 使用高强度、唯一且长期保存的 JWT 密钥。
+- 默认保持公开注册关闭。
+- 不要以管理员或 root 账户运行服务。
+- 限制数据目录和环境配置文件的访问权限。
+- 定期备份完整数据目录并验证备份可恢复。
+- 从可信发布渠道下载，并使用 `SHA256SUMS` 校验归档包。