添加 README.md

2026-09-23 09:19:35 +08:00
commit 9af15b9875
1 changed files with 305 additions and 0 deletions
@@ -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` 校验归档包。