Ubuntu 22.04 安装 dayGLANCE 5.9.0 指南

Ubuntu 22.04 从零安装 dayGLANCE 5.9.0 实测指南：在线源码构建、离线包迁移、桌面应用三方案成章，含 Nginx 托管、同步代理 systemd 托管、Electron 缺库排障实录与升级回退。

dayGLANCEdayGLANCE任务管理2026/10/23

Ubuntu 22.04 安装 dayGLANCE 5.9.0 指南

目标：在一台全新的 Ubuntu 22.04 服务器上从零安装 dayGLANCE 5.9.0（隐私优先的个人日规划与时间块工具），覆盖在线源码构建、离线包迁移、桌面应用安装三种方案，以及 Nginx 托管、同步代理服务、systemd 常驻、升级与卸载的全流程。全部命令与回显均在 Ubuntu 22.04.5 LTS 实机实测取得，逐条照抄即可复现。软件定位与选型背景见 《dayGLANCE 5.9.0 介绍与选型指南》；容器化部署见 《dayGLANCE 5.9.0 Docker Compose 部署指南》。

一、环境信息

本文实测环境（全部命令与回显在这套环境取得）：

  • 操作系统：Ubuntu 22.04.5 LTS（PRETTY_NAME="Ubuntu 22.04.5 LTS"，x86_64）
  • 软件版本：dayGLANCE v5.9.0（官方 GitHub Release，2026-10-15 发布）
  • Nginx：nginx/1.18.0（Ubuntu 22.04 官方仓库自带版本）
  • Node.js：v22.23.4（NodeSource node_22.x 源）、npm 10.9.9
  • Git：2.34.1
  • 应用目录：/opt/dayglance/（源码 /opt/dayglance/src、运行产物 /opt/dayglance/app、代理 /opt/dayglance/proxy）
  • 监听端口：80（Nginx 对外）、127.0.0.1:3001（WebDAV/日历同步代理，仅本机）
  • 版本实查方式：GitHub Releases 页与 releases.atom（查询日期 2026-10-22，最新稳定版 v5.9.0）

💡 说明：dayGLANCE 是"纯前端应用 + 可选同步代理"形态：浏览器里跑的规划器本体只是一堆静态文件，真正的服务端只有两件东西——Nginx（托管静态文件）和一个 Node.js 写的同步代理（转发 WebDAV/日历请求以绕过浏览器跨域限制）。因此"安装 dayGLANCE"= 构建静态产物 + 托管 + 起一个轻量代理，全程不需要数据库，代理服务常驻内存仅约 12 MB。

二、前置条件

  1. 一台 Ubuntu 22.04 服务器（物理机/虚拟机均可），具备 sudo 权限的账户；本文以 root 直接操作；
  2. 服务器能访问 Ubuntu 官方软件源；方案 A 还要求能访问 GitHub（源码与依赖源），受限网络可先为当前会话配置可用的 HTTP 代理再执行；
  3. 方案 B（离线）要求一台能联网的"维护机"（可以是先按方案 A 装好的服务器）用于打包；
  4. 方案 C（桌面应用）要求 Ubuntu 桌面环境（图形会话），纯服务器请跳过该方案；
  5. 磁盘空间：构建过程峰值约需 1 GB（源码 + node_modules 约 538 MB），运行产物仅约 7.4 MB，可先清理构建目录。

三、版本选型说明

dayGLANCE 发版很勤（2026-10 月内连续发布 v5.6.0 → v5.9.0），版本选择要点：

版本线获取方式适用场景
v5.9.0（当前稳定版）GitHub Release 标签 v5.9.0本文基线；--branch v5.9.0 钉扎克隆
latest（最新主干）直接克隆 main 分支想尝鲜周更新；变更风险自担
历史版本回退Release 页各版本资产方案 C 可下载旧 deb/AppImage 平行共存（AppImage）；方案 A 用 git 标签回退

选型结论：生产自托管一律钉扎到具体版本标签（本文 v5.9.0），升级时再切换到新标签重新构建，保证"装的和文档写的一致"。桌面端多版本共存需求用 AppImage（一个文件一个版本），deb 包不支持同机多版本。

四、方案A：在线源码构建安装（服务器推荐方案）

4.1 方案说明

从 GitHub 官方仓库克隆 v5.9.0 源码，在服务器上安装 Node.js 构建依赖并产出静态文件，随后用 Nginx 托管静态产物、以 systemd 常驻官方的 Node.js 同步代理（/api/webdav-proxy/ 与 /api/calendar-proxy/ 两个端点）。该方案版本与官方发布严格一致，产物极轻（约 7.4 MB），适合常驻服务器。

4.2 安装基础依赖

更新软件源索引并安装构建与托管所需的 git、Nginx、curl：

apt-get update
apt-get install -y curl git nginx ca-certificates

apt-get update 实测回显（末尾节选）：

Hit:4 https://deb.nodesource.com/node_22.x nodistro InRelease
Hit:5 http://security.ubuntu.com/ubuntu jammy-security InRelease
Reading package lists...

验证安装结果：

nginx -v && git --version

实测回显：

nginx version: nginx/1.18.0 (Ubuntu)
git version 2.34.1

4.3 安装 Node.js 22

Vite 8 构建链要求 Node.js 20.19+/22.12+。用 NodeSource 官方脚本添加 node_22.x 源后安装：

curl -fsSL https://deb.nodesource.com/setup_22.x -o /tmp/setup_22.x
bash /tmp/setup_22.x
apt-get install -y nodejs

安装过程实测回显（节选）：

Unpacking nodejs (22.23.4-1nodesource1) ...
Setting up nodejs (22.23.4-1nodesource1) ...

验证版本：

node -v && npm -v

实测回显：

v22.23.4
10.9.9

4.4 获取源码（版本钉扎克隆）

以 v5.9.0 标签做浅克隆，钉扎版本并落位到 /opt/dayglance/src：

git clone --depth 1 --branch v5.9.0 https://github.com/krelltunez/dayGLANCE.git /opt/dayglance/src

验证克隆结果与当前提交：

git -C /opt/dayglance/src log --oneline -1

实测回显：

317642a Merge pull request #2115 from krelltunez/settings-device-feedback

4.5 安装依赖并构建

在源码目录安装 npm 依赖（约 538 MB，构建完成后可删）：

cd /opt/dayglance/src
npm install --no-audit --no-fund

实测回显（依赖就绪后复跑的确认输出）：

up to date in 861ms

执行生产构建：

npm run build

实测回显（末尾节选）：

PWA v2.0.0
mode      injectManifest
format:   es
precache  35 entries (5186.63 KiB)
files generated
  dist/sw.js

💡 说明：构建产物的核心是 dist/ 目录（静态文件 + PWA Service Worker）。"precache 35 entries" 表示离线缓存清单收录了 35 个入口资源，首次加载后浏览器即可离线使用。

4.6 部署运行文件

把静态产物与同步代理文件就位到运行目录。注意：代理脚本按仓库目录布局做相对导入，必须保持 docker/proxy-server.mjs 与 api/_ssrfGuard.mjs、api/_readBody.mjs 的相对位置：

mkdir -p /opt/dayglance/app /opt/dayglance/proxy/docker /opt/dayglance/proxy/api
cp -r /opt/dayglance/src/dist/* /opt/dayglance/app/
cp /opt/dayglance/src/docker/proxy-server.mjs /opt/dayglance/proxy/docker/
cp /opt/dayglance/src/api/_ssrfGuard.mjs /opt/dayglance/src/api/_readBody.mjs /opt/dayglance/proxy/api/
du -sh /opt/dayglance/app /opt/dayglance/proxy

实测回显：

7.3M	/opt/dayglance/app
40K	/opt/dayglance/proxy

确认应用目录内容完整（应能看到 index.html、manifest.webmanifest、sw.js、assets/ 等）：

ls /opt/dayglance/app

实测回显：

apple-touch-icon.png
assets
favicon.ico
fonts
icon-144x144.png
icon-16x16.png
icon-192.png
icon-32x32.png
icon-512.png
icon-96x96.png
icon-maskable-192.png
icon-maskable-512.png
icon.icns
icon.ico
index.html
locales
manifest.webmanifest
og-card.png
registerSW.js
service-worker.js
storage-bridge.html
sw.js
theme-init.js

4.7 systemd 托管同步代理服务

创建单元文件 /etc/systemd/system/dayglance-proxy.service：

cat > /etc/systemd/system/dayglance-proxy.service <<'EOF'
[Unit]
Description=dayGLANCE WebDAV/Calendar proxy server
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/dayglance/proxy
ExecStart=/usr/bin/node /opt/dayglance/proxy/docker/proxy-server.mjs
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF

要点逐项说明：

  • ExecStart 直接以 node 运行官方代理脚本，脚本内固定监听 127.0.0.1:3001，仅本机可达，外部请求统一经 Nginx 的 /api/ 反代进入；
  • Restart=on-failure + RestartSec=3：进程异常退出时 3 秒后自动拉起；
  • 代理无外部依赖、无配置文件，内存常驻约 12 MB（实测 Memory: 12.2M）。

4.8 配置 Nginx 站点

创建站点配置 /etc/nginx/sites-available/dayglance：

cat > /etc/nginx/sites-available/dayglance <<'EOF'
server {
    listen 80 default_server;
    server_name _;

    root /opt/dayglance/app;
    index index.html;

    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/json application/javascript application/manifest+json;

    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;

    location = /sw.js {
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    location /api/ {
        client_max_body_size 50m;
        proxy_pass http://127.0.0.1:3001;
        proxy_read_timeout 60s;
        proxy_connect_timeout 30s;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}
EOF
ln -sf /etc/nginx/sites-available/dayglance /etc/nginx/sites-enabled/dayglance
rm -f /etc/nginx/sites-enabled/default

配置逐项说明：

  • root /opt/dayglance/app：静态产物目录；try_files ... /index.html 是单页应用回退（刷新子路径不 404）；
  • location = /sw.js：PWA Service Worker 强制不缓存，否则升级后浏览器可能继续跑旧版本（对应官方自托管文档"更新后请强制刷新"的排障项）；
  • location /api/：把同步代理请求转发给 127.0.0.1:3001；client_max_body_size 50m 是官方镜像同款取值——WebDAV 同步文件整体上传经过这里，Nginx 默认 1 MB 会让超过 1 MB 的同步文件报 413；
  • 读写超时 60s/30s 与官方镜像内 Nginx 配置一致。

语法校验：

nginx -t

实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

4.9 启动服务并验证

加载单元、设置开机自启并立即启动（两条 enable 各针对一个单元）：

systemctl daemon-reload
systemctl enable --now dayglance-proxy.service
systemctl enable --now nginx

systemctl enable --now dayglance-proxy.service 实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/dayglance-proxy.service → /etc/systemd/system/dayglance-proxy.service.

确认两个服务都是 active：

systemctl is-active dayglance-proxy nginx

实测回显：

active
active

验证端口监听（80 对外、3001 仅本机回环）：

ss -ltnp | grep -E ":80 |:3001"

实测回显：

LISTEN 0      511        127.0.0.1:3001      0.0.0.0:*    users:(("node",pid=4212,fd=21))
LISTEN 0      511          0.0.0.0:80        0.0.0.0:*    users:(("nginx",pid=4382,fd=6),("nginx",pid=4381,fd=6),...))

（回显中 nginx worker 进程列表较长，已截断。）

验证 Web 服务四连：

curl -s -o /dev/null -w "首页 HTTP %{http_code}\n" http://localhost/
curl -s http://localhost/ | grep -o "<title>[^<]*</title>"
curl -s -w "\n代理缺参 HTTP %{http_code}\n" http://localhost/api/webdav-proxy/
curl -sI http://localhost/sw.js | grep -i cache-control

实测回显：

首页 HTTP 200
<title>dayGLANCE</title>
{"error":"Missing url parameter"}
代理缺参 HTTP 400
Cache-Control: no-cache, no-store, must-revalidate

逐项解读：首页 200 且标题为 dayGLANCE 说明静态托管正常；/api/webdav-proxy/ 不带 url 参数返回 400 的 JSON 错误，说明 Nginx → Node 代理链路已打通；sw.js 响应头带 no-cache 说明 PWA 缓存规避规则生效。

查看代理服务运行日志（首次启动监听行）：

journalctl -u dayglance-proxy -n 3 --no-pager

实测回显：

Oct 22 18:31:07 abc10f3131a7 systemd[1]: Started dayGLANCE WebDAV/Calendar proxy server.
Oct 22 18:31:07 abc10f3131a7 node[4212]: Proxy server listening on 127.0.0.1:3001

服务详情（内存与进程）：

systemctl status dayglance-proxy --no-pager -n 1

实测回显（节选）：

● dayglance-proxy.service - dayGLANCE WebDAV/Calendar proxy server
     Loaded: loaded (/etc/systemd/system/dayglance-proxy.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-10-22 18:31:07 UTC; 4min 21s ago
   Main PID: 4212 (node)
      Tasks: 7 (limit: 94371)
     Memory: 12.2M

至此服务器端安装完成。浏览器访问 http://<服务器地址>/ 即可开始使用；公网部署务必在前面加 HTTPS 反向代理（浏览器通知等能力要求安全上下文）。

五、方案B：离线包安装（断网服务器）

5.1 方案说明

dayGLANCE 运行态只有"静态文件 + 两个代理脚本"，构建完成后运行不再依赖 node_modules。因此可以在一台联网维护机上完成构建，把约 2.4 MB 的运行产物打成离线包，传输到完全断网的目标服务器展开即可——目标服务器只需已装好 Node.js 运行时与 Nginx（两者均可由 Ubuntu 安装介质或内网源提供）。本节在实测环境内完成了打包 → 展开 → 独立端口部署验证的全流程，证明包内容自足。

5.2 在联网维护机上打包

前提：维护机已按方案 A 的 4.2~4.6 完成构建与部署（或至少完成构建）。打包运行产物：

cd /opt/dayglance && tar czf /opt/dayglance-5.9.0-offline.tar.gz app proxy
ls -lh /opt/dayglance-5.9.0-offline.tar.gz

实测回显：

-rw-r--r-- 1 root root 2.4M Oct 22 18:31 /opt/dayglance-5.9.0-offline.tar.gz

核对包内清单与文件数：

tar -tzf /opt/dayglance-5.9.0-offline.tar.gz | head -6
tar -tzf /opt/dayglance-5.9.0-offline.tar.gz | wc -l

实测回显：

app/
app/fonts/
app/fonts/OFL.txt
app/fonts/lora-500-normal-latin.woff2
app/fonts/lora-700-italic-latin.woff2
app/icon-192.png
67

同时把方案 A 的 Nginx 站点配置与 systemd 单元文件一并拷走（这两份文本文件与产物同版本）：

cp /etc/nginx/sites-available/dayglance /opt/dayglance-offline-nginx-dayglance
cp /etc/systemd/system/dayglance-proxy.service /opt/dayglance-offline-dayglance-proxy.service

5.3 传输到目标服务器

用 scp 把离线包与两份配置传到目标服务器的 /opt/（示例中的 192.168.1.90 请替换为目标服务器真实地址）：

scp /opt/dayglance-5.9.0-offline.tar.gz root@192.168.1.90:/opt/
scp /opt/dayglance-offline-nginx-dayglance root@192.168.1.90:/etc/nginx/sites-available/dayglance
scp /opt/dayglance-offline-dayglance-proxy.service root@192.168.1.90:/etc/systemd/system/dayglance-proxy.service

5.4 目标服务器展开与部署

目标服务器只需 Node.js 运行时与 Nginx（apt-get install -y nodejs nginx，离线时用内网源或 Ubuntu 安装介质），然后：

mkdir -p /opt/dayglance
tar xzf /opt/dayglance-5.9.0-offline.tar.gz -C /opt/dayglance
ln -sf /etc/nginx/sites-available/dayglance /etc/nginx/sites-enabled/dayglance
rm -f /etc/nginx/sites-enabled/default
nginx -t
systemctl daemon-reload
systemctl enable --now dayglance-proxy.service
systemctl enable --now nginx

离线包内容自足性验证（实测：把包展开到全新目录，Nginx 以 8081 端口独立部署该副本）：

mkdir -p /opt/dayglance-pkgtest && tar xzf /opt/dayglance-5.9.0-offline.tar.gz -C /opt/dayglance-pkgtest
ls /opt/dayglance-pkgtest
sed "s|listen 80 default_server;|listen 8081;|; s|root /opt/dayglance/app;|root /opt/dayglance-pkgtest/app;|" /etc/nginx/sites-available/dayglance > /etc/nginx/sites-available/dayglance-pkgtest
ln -sf /etc/nginx/sites-available/dayglance-pkgtest /etc/nginx/sites-enabled/dayglance-pkgtest
nginx -t && systemctl reload nginx
curl -s -o /dev/null -w "8081 离线展开版 HTTP %{http_code}\n" http://localhost:8081/
curl -s -w "\n代理 HTTP %{http_code}\n" http://localhost:8081/api/calendar-proxy/

实测回显：

app
proxy
nginx: configuration file /etc/nginx/nginx.conf test is successful
8081 离线展开版 HTTP 200
{"error":"Missing url parameter"}
代理 HTTP 400

验证完毕后清理验证现场：

rm -f /etc/nginx/sites-enabled/dayglance-pkgtest /etc/nginx/sites-available/dayglance-pkgtest
systemctl reload nginx
rm -rf /opt/dayglance-pkgtest

5.5 方案B验证

在目标服务器上重复方案 A 的 4.9 验证四连（首页 200、标题 dayGLANCE、代理 400、sw.js no-cache 头），全部通过即为部署成功。离线部署的版本以维护机构建时钉扎的标签为准，包名建议带上版本号（如 dayglance-5.9.0-offline.tar.gz）以便多版本管理。

六、方案C：桌面应用安装（.deb / AppImage，Ubuntu 桌面环境）

6.1 方案说明

官方为 Linux 桌面提供 Electron 打包：.deb（装入系统、进应用菜单）与 .AppImage（免安装、单文件）。桌面版在浏览器能力之外增加托盘常驻、本地 MCP 服务器、Stream Deck 监听等能力。⚠️ 该方案需要带图形环境的 Ubuntu 桌面（X11/Wayland 会话），纯服务器环境请用方案 A/B。

6.2 deb 包安装

从官方 Release 下载 v5.9.0 的 amd64 包（x86_64 服务器/桌面；aarch64 机器换 dayglance_5.9.0_arm64.deb）：

curl -LO https://github.com/krelltunez/dayGLANCE/releases/download/v5.9.0/dayglance_5.9.0_amd64.deb
ls -la dayglance_5.9.0_amd64.deb
sha256sum dayglance_5.9.0_amd64.deb

实测回显：

-rw-r--r-- 1 root root 104951364 Oct 22 18:31 dayglance_5.9.0_amd64.deb
ab0e1134bef2b9e5a18bf2c4542b4a4ddbe8a4241ae8c616ea4e038dc621f9b6  dayglance_5.9.0_amd64.deb

安装（apt 会自动解决包声明依赖）：

apt-get install -y ./dayglance_5.9.0_amd64.deb

安装末尾实测回显（节选）：

Processing triggers for libgdk-pixbuf-2.0-0:amd64 (2.42.8+dfsg-1ubuntu0.5) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

校验安装状态与包信息：

dpkg -l dayglance | tail -1
dpkg -s dayglance | grep -E "^(Version|Architecture)"
dpkg -L dayglance | wc -l
which dayglance

实测回显：

ii  dayglance      5.9.0        amd64
Architecture: amd64
Version: 5.9.0
93
/usr/bin/dayglance

包声明的依赖（供离线桌面机备料，apt-cache depends dayglance 实测）：

  Depends: libgtk-3-0
  Depends: libnotify4
  Depends: libnss3
  Depends: libxss1
  Depends: libxtst6
  Depends: xdg-utils
  Depends: libatspi2.0-0
  Depends: libuuid1
  Depends: libsecret-1-0

6.3 缺库排障实录（Electron 运行库）

包声明依赖不含 Electron 实际需要的 libgbm1 与 libasound2，在最小安装的桌面上首次启动会连续报缺库。以下为实测排障全过程，读者遇到同样报错按顺序补库即可：

第一次启动报缺 libgbm.so.1：

dayglance

实测回显：

dayglance: error while loading shared libraries: libgbm.so.1: cannot open shared object file: No such file or directory

补 libgbm1 后再启动，轮到缺 libasound.so.2：

apt-get install -y libgbm1
dayglance

实测回显：

dayglance: error while loading shared libraries: libasound.so.2: cannot open shared object file: No such file or directory

补齐第二轮运行库后再启动，报 root 沙箱限制：

apt-get install -y libgtk-3-0 libnss3 libasound2 libxss1
dayglance

实测回显：

[1022/183409.938933:FATAL:electron/shell/app/electron_main_delegate.cc:225] Running as root without --no-sandbox is not supported. See https://crbug.com/638180.

root 用户加 --no-sandbox 参数后触达最后一个边界——图形环境缺失（这正是"桌面版必须装在桌面系统上"的实测证据）：

dayglance --no-sandbox

实测回显：

[6359:1022/183418.308944:ERROR:ui/ozone/platform/x11/ozone_platform_x11.cc:257] Missing X server or $DISPLAY
[6359:1022/183418.308971:ERROR:ui/aura/env.cc:246] The platform failed to initialize.  Exiting.

结论：普通桌面用户（非 root）在完整桌面会话里从应用菜单或终端执行 dayglance 即可正常启动；上面两行 $DISPLAY 报错只会在无图形会话的环境出现，属预期边界而非故障。

6.4 AppImage 方式（免安装、多版本共存）

AppImage 是单文件免安装形态，适合多版本共存或无 root 权限的桌面。下载并赋权：

curl -LO https://github.com/krelltunez/dayGLANCE/releases/download/v5.9.0/dayGLANCE-5.9.0-x86_64.AppImage
chmod +x dayGLANCE-5.9.0-x86_64.AppImage
ls -la dayGLANCE-5.9.0-x86_64.AppImage

实测回显：

-rwxr-xr-x 1 root root 136035299 Oct 22 18:33 dayGLANCE-5.9.0-x86_64.AppImage

查看内嵌版本号：

./dayGLANCE-5.9.0-x86_64.AppImage --appimage-version

实测回显：

Version: effcebc

系统缺 FUSE 时不用装库，直接解包运行（解包目录 345 MB，实测）：

./dayGLANCE-5.9.0-x86_64.AppImage --appimage-extract
ls squashfs-root/ | head -5
du -sh squashfs-root

实测回显：

AppRun
LICENSE.electron.txt
LICENSES.chromium.html
chrome-sandbox
chrome_100_percent.pak
345M    squashfs-root

之后执行 ./squashfs-root/AppRun --no-sandbox 启动（同样需要图形会话）。不同版本的 AppImage 文件名带版本号，可同时保存在 ~/.local/bin/ 下按需启动，这是桌面端多版本管理的推荐方式。

七、方案对比与选择建议

维度方案A 在线源码构建方案B 离线包方案C 桌面应用
目标环境可联网 Ubuntu 服务器断网 Ubuntu 服务器Ubuntu 桌面环境
是否需 Node.js构建期需要（22.12+）仅运行时需要（代理用）不需要（Electron 自带）
是否需 Nginx需要（静态托管 + 反代）需要不需要
systemd 托管dayglance-proxy + nginx同方案A无（桌面应用自管理）
监听端口80 + 127.0.0.1:3001同方案A无监听端口（本地 MCP 除外）
多版本管理git 标签切换重建按版本命名的离线包AppImage 多文件共存
产物体量运行 7.4 MB + 代理 40 KB离线包 2.4 MBdeb 约 105 MB / AppImage 约 136 MB

选择建议：常驻服务器给浏览器用 → 方案 A；内网隔离环境 → 方案 B（维护机构建一次，多处展开）；要在自己每天用的桌面机获得托盘/MCP 等原生能力 → 方案 C。三种方案数据同构（都走浏览器本地存储 + 同步通道），可并存使用同一份数据。

八、配置说明

dayGLANCE 服务端几乎没有传统意义上的配置文件，需要掌握的配置位置如下：

  • Nginx 站点：/etc/nginx/sites-available/dayglance——端口（listen）、产物目录（root）、同步上传上限（client_max_body_size）、Service Worker 缓存策略；改完执行 nginx -t && systemctl reload nginx 生效；
  • 代理服务单元：/etc/systemd/system/dayglance-proxy.service——工作目录与启动命令；改完 systemctl daemon-reload && systemctl restart dayglance-proxy；
  • 代理私网封锁开关：代理进程读取环境变量 WEBDAV_PROXY_BLOCK_PRIVATE，设为 1/true 时拒绝私网/局域网同步目标（与托管版行为一致）。systemd 形态在单元文件 [Service] 段加一行 Environment=WEBDAV_PROXY_BLOCK_PRIVATE=1 后重启服务；该变量与各错误分支的实测行为详见 《dayGLANCE 5.9.0 配置参数详解》；
  • 应用内设置（浏览器端，跟随浏览器存储）：云同步（Settings → Cloud Sync）、日历订阅（Settings → Calendar Sync）、AI 加载项等都在 Web 界面内配置，服务器侧无对应文件；
  • HTTPS：对外服务在 Nginx 前再挂一层 TLS 终结（或改用 443 站点证书块），浏览器通知与 PWA 安装能力依赖 HTTPS 安全上下文。

⚠️ 注意：/api/webdav-proxy/ 与 /api/calendar-proxy/ 是无鉴权转发端点，官方明确要求不要把实例裸暴露公网；务必前置带认证的反向代理或仅在内网使用。

九、升级与版本管理

方案 A 的升级流程（以升级到未来新版本为例，当前 v5.9.0 已是最新，git pull 返回如下）：

cd /opt/dayglance/src
git pull

实测回显：

Already up to date.

正式升级到指定新版本时，把标签切换到目标版本后重跑构建与部署（以切到 v5.9.0 为例，同型命令适用于任何后续标签）：

cd /opt/dayglance/src
git fetch --tags --force
git checkout v5.9.0
npm install --no-audit --no-fund
npm run build
rm -rf /opt/dayglance/app/*
cp -r dist/* /opt/dayglance/app/
cp docker/proxy-server.mjs /opt/dayglance/proxy/docker/
cp api/_ssrfGuard.mjs api/_readBody.mjs /opt/dayglance/proxy/api/
systemctl restart dayglance-proxy
curl -s -o /dev/null -w "升级后首页 HTTP %{http_code}\n" http://localhost/

升级后验证口径与 4.9 相同（首页 200、代理 400）。若浏览器显示旧版本，强制刷新（Ctrl+Shift+R）清掉 PWA 缓存。回退版本：把 git checkout 指向旧标签重跑构建即可；方案 B 直接用旧版离线包覆盖展开；方案 C 的 deb 回退需先 apt-get remove dayglance 再装旧包，AppImage 则保留旧文件直接运行。

十、常见问题（FAQ）

Q1：首页 502 或 /api/ 报错怎么排查？ 按链路逐段查：systemctl is-active dayglance-proxy nginx 应均为 active；ss -ltnp | grep 3001 应看到 node 监听 127.0.0.1:3001；journalctl -u dayglance-proxy -n 20 --no-pager 看代理是否打印过 Proxy server listening on 127.0.0.1:3001。实测正常状态就是 4.9 节的三段回显，任何一段对不上就修对应环节。

Q2：同步文件上传报 413 Request Entity Too Large？ Nginx 的 client_max_body_size 太小。本文配置取官方同款 50m；同步文件是整体上传，超过该值即 413。改配置后 nginx -t && systemctl reload nginx。

Q3：升级后页面还是旧版、或功能表现异常？ PWA 的 Service Worker 缓存了旧资源。先确认服务器产物已更新（curl -s http://localhost/ | grep -o 'assets/index-[^"]*\.js' 对比文件名），再在浏览器强制刷新（Ctrl+Shift+R）。

Q4：浏览器通知不弹？ 通知要求 HTTPS 安全上下文。给站点配证书或经支持 TLS 的反向代理访问。

Q5：桌面版启动报缺库（libgbm.so.1 / libasound.so.2）？ 见 6.3 排障实录，依次补 libgbm1、libasound2（连同 libgtk-3-0 libnss3 libxss1）。

Q6：root 运行桌面版报 "Running as root without --no-sandbox is not supported"？ Electron 的 Chromium 沙箱不允许 root 直跑；加 --no-sandbox 参数或改用普通用户启动（推荐后者）。

Q7：自托管实例能被多个设备共用吗？ 可以——它本质是"数据各存各的浏览器 + 各自配同步"。多设备一致性的正确姿势是统一配置同一个 WebDAV/Nextcloud 同步目标，而不是共享一个服务器目录。

十一、卸载与清理

方案 A/B 的卸载（按占用反序拆除）：

systemctl disable --now dayglance-proxy.service
rm -f /etc/systemd/system/dayglance-proxy.service
systemctl daemon-reload
rm -f /etc/nginx/sites-enabled/dayglance /etc/nginx/sites-available/dayglance
systemctl reload nginx
rm -rf /opt/dayglance

Nginx 与 Node.js 若为其他业务共用则保留；确属专机可 apt-get purge -y nginx nodejs 清除。方案 C 的卸载：

apt-get remove -y dayglance

实测回显（节选）：

Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

AppImage 形态直接删除对应文件即可；如做过 --appimage-extract，连 squashfs-root/ 目录一起删。

十二、参考链接