适用于:想把 Notely 从 EdgeOne Pages 搬到自己的服务器,或直接以自托管形态起步。
三种方案共用同一套业务代码,功能完全一致(笔记 / 标签 / 任务 / 项目 / 记忆 / 统计 / 时区 / 附件直传 / MCP / 快捷指令 / WebDAV 备份 / 回收站 / AI),数据全部持久化在.data目录,可在 EdgeOne 与服务器之间双向迁移,无锁定。
前置知识:Notely 的两种运行形态
cloud-functions/ ← EdgeOne Pages 部署入口(api / mcp / file 三个 catch-all)
server.js ← 自托管运行入口(Node http + 本地适配器,模拟 Blob 强一致 + KV 落盘)
site/ ← 前端(静态文件由 server.js 直接伺服,已内置 SPA 回退)在 EdgeOne 上部署时跑的是 cloud-functions/,自托管时跑的是 server.js。两者读同一份业务核心 cloud-functions/_lib/core/app.js,所以功能完全一致。自托管时 KV 会落盘到 .data/state/kv.json,重启不丢(包括 AI 每日限流计数)。
三种方案总览
| 方案 A | 方案 B | 方案 C | |
|---|---|---|---|
| 运行方式 | Docker Compose + Caddy | Node 直跑 + Nginx | Docker 单容器 + Nginx/面板 |
| HTTPS | Caddy 自动申请/续期 | 面板 / certbot | 面板 / certbot |
| 内存占用(约) | 130MB(已有 Docker)/ 230MB(无 Docker) | ~100MB(复用 Nginx) | ~420MB(含面板) |
| 需要改代码 | ❌ 不需要 | ❌ 不需要 | ❌ 不需要 |
| 适合场景 | 已用 Docker 的机器 | 轻量小鸡,追求最省资源 | 习惯面板统一管域名 |
资源结论:面板(宝塔/1panel)本身 200-500MB,是最大的隐性开销;Docker daemon 常驻约 100MB。极简场景 = node + systemd + 复用已有 Nginx,最省。
共同前置准备(三种方案都要做)
1. 拉取代码
git clone https://github.com/kinga-a/notely.git
cd notely2. 准备域名与 DNS
- 一个域名(或子域名),解析 A/AAAA 记录到服务器公网 IP
- 自托管形态必须有公网可访问域名——附件直传签名 URL 依赖它(见下方注意事项)
3. 生成密钥
openssl rand -hex 32 # 生成 NOTELY_SECRET(会话/令牌签名密钥)
openssl rand -hex 16 # 生成 NOTELY_INTERNAL_TOKEN(内部定时任务鉴权)
openssl rand -hex 16 # 生成 MCP_TOKEN(MCP 端点令牌,强烈建议设置)4. 配置环境变量
复制模板并按注释填写(方案 A/B 用同一个模板):
cp .env.docker.example .env| 变量 | 必填 | 说明 |
|---|---|---|
NOTELY_SECRET | ✅ | 签名密钥,必须改为随机值,否则有安全风险 |
NOTELY_INTERNAL_TOKEN | 建议 | 内部定时任务(daily)鉴权令牌;留空回退用 NOTELY_SECRET |
MCP_TOKEN | 建议 | MCP 端点令牌(客户端 Bearer 访问 /mcp);不设置则 /mcp 无鉴权开放 |
NOTELY_DOMAIN | ✅ | 公网域名,如 notes.example.com(方案 A 专用,同时用于 Caddy 反代与附件直传前缀) |
NOTELY_LOCAL_PUBBASE | ✅ | 附件直传签名 URL 前缀,必须填公网域名(方案 B/C 手动填) |
OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL | 选填 | OpenAI 兼容协议任意一家;留空则 AI 功能走本地 mock(演示模式) |
MAKERS_MODELS_KEY / MAKERS_MODEL | 选填 | Makers Models 通道,填其一即启用真实模型 |
AI_DAILY_LIMIT | 选填 | 每日 AI 调用护栏,默认 80,重启不丢 |
TRASH_RETENTION_DAYS | 选填 | 回收站保留天数,默认 30,超期由 daily 硬删;0 关闭自动清理 |
5. 配置定时任务(必须!)
每日回顾生成 + 回收站清理依赖外部 cron 触发内部接口,不配则这两项功能不工作:
0 1 * * * curl -fsS -X POST https://<你的域名>/api/internal/daily -H "x-notely-token: <NOTELY_INTERNAL_TOKEN>"添加到宿主机 crontab:crontab -e 粘贴上面一行,把域名和 token 换成你的。
方案 A:Docker Compose + Caddy(推荐,零改动)
仓库自带 docker-compose.yml(notely + caddy 双容器)、Caddyfile(自动 HTTPS)、Dockerfile(node:20-alpine 多阶段构建)。
步骤
# 1. 已在上面前置步骤配好 .env(NOTELY_DOMAIN 必填)
# 2. 改 Caddyfile:把 bj.y11.fun 换成你的域名
vim Caddyfile
# bj.y11.fun {
# encode gzip
# reverse_proxy notely:3000
# }
# 3. 构建并启动(首次构建约 1-2 分钟)
docker compose up -d --build
# 4. 查看状态(健康检查通过即就绪)
docker compose ps验证
# Caddy 自动申请证书,首次签发后即可 HTTPS 访问
curl -I https://你的域名
# 应返回 200 / 301 正常响应浏览器打开 https://你的域名 → 首次访问设置登录密码 → 完成。
运维命令
docker compose logs -f notely # 看应用日志
docker compose down # 停止(数据保留在卷中)
docker compose up -d --build # 升级 / 重新构建
docker volume ls # notely-data 就是全部数据方案 A 特有的坑:NOTELY_LOCAL_PUBBASE 由 compose 按 NOTELY_DOMAIN 自动推导,不要手动改它;容器网络内 Caddy 反代目标是服务名 notely:3000,不是 IP。
方案 B:Node 直跑 + systemd + Nginx(最省资源)
不引入 Docker,直接用 server.js 起进程,Nginx 做反向代理 + 证书(复用服务器已有 Nginx,或面板的 Nginx)。
步骤
# 1. 安装依赖(生产依赖即可)
npm ci --omit=dev
# 2. 配好 .env(方案 B 手动填 NOTELY_LOCAL_PUBBASE)
# NOTELY_LOCAL_PUBBASE=https://你的域名
# NOTELY_SECRET=你的随机密钥
# MCP_TOKEN=你的令牌
# 3. 建议用独立用户运行(安全)
sudo useradd -r -s /bin/false notely
sudo chown -R notely:notely /opt/notely # 假设代码放在 /opt/notely
# 4. 建 systemd 服务
sudo vim /etc/systemd/system/notely.servicenotely.service 内容:
[Unit]
Description=Notely self-hosted
After=network.target
[Service]
Type=simple
User=notely
WorkingDirectory=/opt/notely
EnvironmentFile=/opt/notely/.env
ExecStart=/usr/bin/node server.js
Restart=always
RestartSec=3
# 可选:限制内存防 OOM
# MemoryMax=300M
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now notely
sudo systemctl status notely # 确认 active (running)
curl -I http://127.0.0.1:3000/api/auth/status # 探活Nginx 反代配置
server {
listen 80;
server_name 你的域名;
# 如果走面板/证书工具,让它接管 443 和证书,这里只写反代核心
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_buffering off; # 附件/流式场景更稳
}
}证书:用面板一键申请,或 certbot --nginx -d 你的域名。HTTPS 必须启用——附件直传和 WebDAV 备份都依赖安全上下文。
运维命令
sudo systemctl restart notely # 重启
sudo journalctl -u notely -f # 看日志方案 C:Docker 单容器 + 面板反代
用现成 Dockerfile 构建镜像,面板只负责域名/证书/反代(不引入 Caddy)。
步骤
# 1. 构建镜像
docker build -t notely:latest .
# 2. 配好 .env(方案 C 手动填 NOTELY_LOCAL_PUBBASE)
# 3. 启动容器(数据卷 + 环境变量)
docker run -d \
--name notely \
--restart unless-stopped \
-p 127.0.0.1:3000:3000 \
-v notely-data:/app/.data \
--env-file .env \
-e NOTELY_LOCAL_PUBBASE=https://你的域名 \
-e TZ=Asia/Shanghai \
notely:latest
# 4. 确认健康
docker logs -f notely只映射 127.0.0.1:3000:容器只对本机开放,外网流量统一走面板的 Nginx 反代,更安全。面板侧配置(1panel / 宝塔通用)
- 创建网站 → 域名填你的域名 → 选择「反向代理」
- 目标地址填
http://127.0.0.1:3000 - 开启 SSL(面板自动申请证书)
- 保存后访问
https://你的域名验证
运维命令
docker restart notely
docker logs -f notely
docker run -d --name notely ... # 更新时换新 tag 重建从 EdgeOne 迁移数据到服务器(三种方案通用)
- 导出:在现网(EdgeOne 版)「我的 → 备份/恢复」导出
notely_backup.json(含全部笔记/回收站/归档/项目/任务/记忆/时区) - 恢复:服务器版首次打开设置密码,登录后「恢复」导入该 JSON(或
POST /api/restore) - 迁移附件二进制(备份 JSON 只含元数据,附件按正文引用迁移):
node scripts/export-uploads.js notely_backup.json --base https://现网域名 --dir .data脚本从现网 /api/file 拉取附件并还原为原始二进制(幂等可重跑,--dry-run 预览)。
- 验证:登录 → 笔记数/统计一致 → 打开含图片的笔记 → 快捷指令与 MCP 各打一遍
反向(服务器 → EdgeOne)同理:网页「导出」→ EdgeOne「恢复」+ 附件反向迁移。数据格式同源,无锁定,随时可回滚。
重点注意事项(最容易踩的坑)
⚠️ 1. NOTELY_LOCAL_PUBBASE 必须填公网域名(附件直传的命门)
这是自托管最容易出问题的一项:附件上传走「签名直传」,签名 URL 的前缀就是这个变量。填 localhost 或容器内地址,浏览器拿到的直传地址不可访问,附件上传/访问会失败。方案 A 由 compose 自动推导,方案 B/C 必须手动填 https://你的域名。
⚠️ 2. NOTELY_SECRET 必须改为随机值
留空会回退到 dev-secret-change-me 这种默认密钥——别人知道源码就能伪造会话。必须 openssl rand -hex 32 生成。
⚠️ 3. MCP_TOKEN 建议必须设置
不设置则 /mcp 端点无鉴权开放,等于把笔记数据裸奔在公网。设置后用 Bearer 访问(Authorization: Bearer <MCP_TOKEN>)。
⚠️ 4. 定时任务(cron)必须配置
每日回顾生成 + 回收站清理都靠它。不配 = 这两个功能静默失效。EdgeOne 版有平台调度,自托管没有,必须自己在宿主机 crontab 加那行 curl。
⚠️ 5. 数据全部在 .data,备份 = 备份这个目录
笔记/索引/附件/AI 缓存/KV 全在 /app/.data(或 volume notely-data)。定期备份:tar -czf backup.tar.gz .data 或直接卷拷贝。迁移 = 复制这个目录,无缝搬家。
⚠️ 6. AI 功能默认是演示模式
不填任何 AI Key,AI 相关功能走本地 mock(演示返回),不会真调模型。要真用需填 OPENAI_API_KEY+OPENAI_BASE_URL+OPENAI_MODEL(OpenAI 官方 / DeepSeek / 任意兼容协议)或 MAKERS_MODELS_KEY。AI_DAILY_LIMIT 默认 80 次/天护栏,经落盘 KV 计数,重启不丢。
⚠️ 7. 时区
compose 已设 TZ=Asia/Shanghai,方案 B/C 也建议加上(影响「每日回顾」按本地日期归组)。
⚠️ 8. 不要为单应用装面板(资源角度)
宝塔全家桶 300-500MB、1panel 约 200MB,比 Notely 本身(node 进程 ~70MB)还重。轻量小鸡用方案 B + systemd 最省;已有 Docker 的机器方案 A 最省事。方案 C 适合你已经习惯用面板统一管理域名的场景。
⚠️ 9. 端口冲突
方案 A 占用 80/443(Caddy);方案 B/C 的 Nginx 也占用 80/443。服务器上若有其他站点,一个域名只能有一个反代目标,注意别互相覆盖。
⚠️ 10. 健康检查
Dockerfile 内置了 HEALTHCHECK(wget /api/auth/status)。自检时可以直接 curl -I http://127.0.0.1:3000/api/auth/status——返回非 5xx 即服务正常(未设置密码前该接口返回 401 属预期,说明服务活着)。
部署后验证清单
- ☐
https://你的域名打开,首次设置登录密码 - ☐ 写一条笔记 → 发送按钮变勾 ✓(5 秒后变回)
- ☐ 写一条超过 300 字的笔记 → 出现「展开全文」→ 展开 → 收起(按钮跟随滚动)
- ☐ 传一张图片附件 → 刷新后图片可正常加载(验证
NOTELY_LOCAL_PUBBASE) - ☐ 打开「我的 → WebDAV」→ 连接测试(验证 HTTPS 上下文)
- ☐ crontab 已加 daily 行,次日确认「今日回顾」有内容
- ☐
MCP_TOKEN已设置,/mcp不带 token 被拒 - ☐ 数据目录有备份(
.data或 volume)
结语
Notely 自托管最舒服的一点:部署形态就是开发形态——server.js 本身就是生产入口,没有为服务器部署做任何特殊改造,数据和 EdgeOne 形态同源,随时可以来回切。选哪个方案,本质是选「你习惯用哪套基础设施」:爱 Docker 用 A,抠资源用 B,爱面板用 C。
评论