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