nestify-releases/README.md

吾域服务器(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：

sha256sum -c SHA256SUMS

Windows 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 密钥：

openssl rand -hex 32

请长期保存同一个密钥。修改密钥会使所有现有登录会话失效。

Linux 部署

1. 解压

tar -xzf nestify-v1.0.0-linux-amd64.tar.gz
cd nestify-v1.0.0-linux-amd64
chmod +x nestify

ARM64 设备请替换为对应的 linux-arm64 文件。

2. 首次前台运行

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：

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：

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

保护配置文件：

sudo chmod 600 /etc/nestify.env

创建 /etc/systemd/system/nestify.service：

[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

启动服务：

sudo systemctl daemon-reload
sudo systemctl enable --now nestify
sudo systemctl status nestify

查看日志：

journalctl -u nestify -f

Windows 部署

1. 解压

将 ZIP 解压到固定目录，例如：

C:\Nestify

建议将数据放在：

C:\Nestify\data

2. 使用 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 地址为：

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：

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 校验归档包。