Notely 自托管部署全攻略:三种方案(Docker Compose / Node 直跑 / 单容器+面板)
侧边栏壁纸
博主昵称
5i

  • 累计撰写 24 篇文章
  • 累计收到 0 条评论

Notely 自托管部署全攻略:三种方案(Docker Compose / Node 直跑 / 单容器+面板)

5i
5i
2026-10-25 / 0 评论 / 12 阅读 / 正在检测是否收录...
适用于:想把 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 + CaddyNode 直跑 + NginxDocker 单容器 + Nginx/面板
HTTPSCaddy 自动申请/续期面板 / 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 notely

2. 准备域名与 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.service

notely.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.target
sudo 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 / 宝塔通用)

  1. 创建网站 → 域名填你的域名 → 选择「反向代理」
  2. 目标地址填 http://127.0.0.1:3000
  3. 开启 SSL(面板自动申请证书)
  4. 保存后访问 https://你的域名 验证

运维命令

docker restart notely
docker logs -f notely
docker run -d --name notely ...   # 更新时换新 tag 重建

从 EdgeOne 迁移数据到服务器(三种方案通用)

  1. 导出:在现网(EdgeOne 版)「我的 → 备份/恢复」导出 notely_backup.json(含全部笔记/回收站/归档/项目/任务/记忆/时区)
  2. 恢复:服务器版首次打开设置密码,登录后「恢复」导入该 JSON(或 POST /api/restore)
  3. 迁移附件二进制(备份 JSON 只含元数据,附件按正文引用迁移):
node scripts/export-uploads.js notely_backup.json --base https://现网域名 --dir .data

脚本从现网 /api/file 拉取附件并还原为原始二进制(幂等可重跑,--dry-run 预览)。

  1. 验证:登录 → 笔记数/统计一致 → 打开含图片的笔记 → 快捷指令与 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。

0

评论

博主关闭了所有页面的评论