# 吾域服务器(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` 校验归档包。