dayGLANCE 5.9.0 配置参数详解

目标：把自托管 dayGLANCE 5.9.0 时能碰到的所有配置参数一次讲透——服务端唯一环境变量 WEBDAV_PROXY_BLOCK_PRIVATE、官方镜像内置的 Nginx 参数、同步代理进程的行为参数、SSRF 网段策略，以及浏览器内的应用设置（云同步、自动备份、加密、集成项），每一项都给出查看方式、默认值、修改方法与实测证据。全部命令与回显均在 Ubuntu 22.04.5 LTS + dayGLANCE 5.9.0 官方镜像实例实测取得，逐条照抄即可复现。部署方法见 《dayGLANCE 5.9.0 Docker Compose 部署指南》，源码自建形态见 《Ubuntu 22.04 安装 dayGLANCE 5.9.0 指南》，软件定位见 《dayGLANCE 5.9.0 介绍与选型指南》。

一、环境信息

本文所有实测在这套环境取得：

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• dayGLANCE：v5.9.0（官方 GitHub Release，2026-10-15 发布；2026-10-22 实查 Releases 为最新稳定版）
• 部署形态：官方镜像 ghcr.io/krelltunez/dayglance:latest（digest sha256:4537e3206e3cf4223b064ace01d877d653c45cb0251bb6cc4a7eb7c141d557dd），镜像内置 Nginx 1.31.7 + Node.js 同步代理
• 实例 A：默认配置（未设置封锁变量），服务端口 8131
• 实例 B：WEBDAV_PROXY_BLOCK_PRIVATE=1 封锁对照实例，服务端口 8133
• 代理行为测试目标：静态假目标 10.89.59.2（返回固定文本 fixture-for-webdav-proxy）、鉴权假目标 10.89.59.4:8085（Basic 认证账号 admin / q1w2e3r4，受保护路径未带凭据返回 401）
• 配置参数溯源文件：镜像内 /etc/nginx/conf.d/default.conf、/app/docker/proxy-server.mjs、/app/api/_ssrfGuard.mjs（均于 2026-10-23 自运行实例中取出）

💡 说明：dayGLANCE 的配置分三层——服务端（环境变量 + 镜像内置配置文件，改完要重建实例）、同步代理行为（写在镜像内源码里，只能读不能改，出问题查这里）、浏览器内应用设置（存在浏览器 localStorage，随设备各自独立）。服务端可调的只有一个环境变量，这是它与常规自托管应用最大的差异：绝大多数"配置"都在你自己的浏览器里。

二、前置条件

1. 一个已部署的 dayGLANCE 5.9.0 实例（官方镜像部署按 《dayGLANCE 5.9.0 Docker Compose 部署指南》 第四章，源码自建按 《Ubuntu 22.04 安装 dayGLANCE 5.9.0 指南》）；本文以官方镜像部署为基线，源码自建形态的差异在第三章单独标注；
2. 服务器上可执行 curl（Ubuntu 22.04 自带）；
3. 容器部署形态需要能执行 docker exec 查看实例内部文件；
4. 查看浏览器内设置需要一台装有现代浏览器（Chrome/Edge/Firefox 均可）的设备。

三、参数查看与修改方式

本章先解决"参数在哪、怎么查、改了怎么生效"的问题，后续章节再逐项展开。

3.1 三层配置总览

3.2 服务端参数查看（实测）

查看实例环境变量（过滤出 dayGLANCE 认识的那个）：

docker exec dayglance env | grep WEBDAV

默认部署的实例没有任何输出（变量未设置，走默认放行行为）；带封锁部署的实例输出：

WEBDAV_PROXY_BLOCK_PRIVATE=1

查看镜像内置 Nginx 配置与代理源码：

docker exec dayglance cat /etc/nginx/conf.d/default.conf
docker exec dayglance cat /app/docker/proxy-server.mjs
docker exec dayglance cat /app/api/_ssrfGuard.mjs

三条命令均有完整回显（内容在第五、六节逐段解说）。源码自建形态（《Ubuntu 22.04 安装 dayGLANCE 5.9.0 指南》 方案 A）的对应位置：Nginx 站点配置在 /etc/nginx/sites-available/dayglance，代理脚本在 /opt/dayglance/proxy/proxy-server.mjs，环境变量通过 systemd 单元的 Environment= 行注入，改后 systemctl restart dayglance-proxy 生效（每条命令针对一个单元）。

3.3 浏览器内设置查看（实测）

应用内入口：右上角 Settings（齿轮图标），设置面板包含 Appearance（外观）、Cloud Sync（云同步）、Calendar（日历）、Integrations（集成）、Notifications（通知）、Data（数据）等分区；修改即时保存到当前浏览器的 localStorage。

验证"设置确实存在浏览器里"的方法：浏览器 DevTools → Console 执行 Object.keys(localStorage).length，在实测实例上返回 134 个键（2026-10-23 实测）；这些键的完整清单与分类见 5.5 节。

四、参数总览

先给一张总表建立全貌，每一项的实测细节在第五节展开。

服务端环境变量（唯一）：

镜像内置 Nginx 关键参数（/etc/nginx/conf.d/default.conf）：

同步代理行为参数（/app/docker/proxy-server.mjs）：

SSRF 网段策略（/app/api/_ssrfGuard.mjs）：

浏览器内应用设置（localStorage，共 134 个键，2026-10-23 实测）：

五、核心参数分类详解

5.1 服务端环境变量：WEBDAV_PROXY_BLOCK_PRIVATE

这是官方镜像支持的唯一环境变量（镜像源码 /app/docker/proxy-server.mjs 中仅读取这一个 process.env）。它控制同步代理对私网/局域网同步目标的态度：

四个状态的实测。默认状态（未设置），私网目标正常放行：

curl -s -w "\n[%{http_code}]\n" "http://localhost:8131/api/webdav-proxy/?url=http%3A%2F%2F10.89.59.2%2Fhello.txt"

fixture-for-webdav-proxy

[200]

设为 1 的对照实例，同一目标被拒：

curl -s -w "\n[%{http_code}]\n" "http://localhost:8133/api/webdav-proxy/?url=http%3A%2F%2F10.89.59.2%2Fhello.txt"

{"error":"Private/reserved addresses are not allowed"}
[403]

设为小写 true 的对照实例（新建实例、删除后重建成 TRUE 大写实例），行为与 1 完全一致：

{"error":"Private/reserved addresses are not allowed"}
[403]

而大写 TRUE 的实例——变量不生效，私网目标照样 200：

fixture-for-webdav-proxy

[200]

⚠️ 注意：取值是源码里的精确字符串匹配（process.env.WEBDAV_PROXY_BLOCK_PRIVATE === '1' || === 'true'）。写成 TRUE、yes 不会报任何错，只会安静地不生效——部署"封锁模式"后务必用上面的 curl 复测一条私网目标，确认返回 403 而不是 200。

保留网段不受该变量影响，两种状态下都拒绝（实测，默认放行的 8131 实例同样被拒）：

curl -s -w "\n[%{http_code}]\n" "http://localhost:8131/api/webdav-proxy/?url=http%3A%2F%2F169.254.169.254%2Flatest%2Fmeta-data%2F"

{"error":"Private/reserved addresses are not allowed"}
[403]

💡 技术拓展：这类"代理会替你向任意地址发请求"的端点，防御的正是 SSRF（Server-Side Request Forgery，服务端请求伪造）——攻击者借你的服务器当跳板访问内网。常见防御手段对比：

手段	原理	取舍
网段封锁（本方案）	按目标 IP 网段拒绝危险地址	实现简单、对自托管友好；保留网段硬编码
出口白名单	只允许访问显式登记的目标	最严格，但牺牲"随手指向新 NAS"的灵活性
出口代理隔离	代理流量经无内网权限的独立出口	隔离彻底，架构成本高

dayGLANCE 采用"网段封锁 + 默认放行私网 + 保留网段一律拒绝"的组合，并保留 WEBDAV_PROXY_BLOCK_PRIVATE=1 一键对齐托管版行为——对自托管场景这是灵活性优先的合理取舍。

5.2 镜像内置 Nginx 参数（逐项）

以下配置从运行实例中取出（docker exec dayglance cat /etc/nginx/conf.d/default.conf，全文 80 行），是实例对外行为的完整定义。逐段解说：

服务器基础段：listen 80（容器内固定 80）、server_name localhost、站点根 /usr/share/nginx/html（静态产物）、index index.html。宿主侧只需要改端口映射，这两行不用动。

gzip 段：gzip on、gzip_vary on、gzip_min_length 1024（1 KB 以下不压缩），压缩类型覆盖 text/css/js/json/xml/manifest 等 8 类。应用静态产物中最大的 JS 约 3.9 MB，压缩后传输体积大幅下降——这是页面首屏加载的关键参数，保持默认即可。

安全响应头（6 项，逐条）：

CSP 值得单独说明：connect-src * 放开了同步/订阅请求的目标（代理功能需要），script-src 'self' 'unsafe-inline' 只允许同源脚本与内联脚本——想往页面里注入第三方统计/脚本会被 CSP 拦截，这是设计行为不是故障。验证方法（实测，安全头在代理响应上也追加）：

curl -s -I -X OPTIONS "http://localhost:8131/api/webdav-proxy/?url=http%3A%2F%2F10.89.59.2%2Fhello.txt"

HTTP/1.1 204 No Content
Server: nginx/1.31.7
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, PUT, DELETE, MKCOL, PROPFIND, OPTIONS
Access-Control-Allow-Headers: Authorization, X-WebDAV-Auth, Content-Type, Depth, If-Match, If-None-Match
Access-Control-Max-Age: 86400
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains

PWA 缓存豁免段：/sw.js、/manifest.webmanifest、/service-worker.js 三个精确匹配 location 强制 no-cache, no-store, must-revalidate——Service Worker 与清单必须每次拿最新的，否则 PWA 升级后浏览器还在跑旧版本（这是"升级后页面没变"问题根源之一，处置见第七节 Q5）。

静态资源缓存段：正则匹配 js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot 后缀，expires 1y + Cache-Control: public, immutable。文件名带内容哈希（如 index-CzAdUpxJ.js），内容变文件名变，一年强缓存是安全的。

/api/ 反代段：proxy_pass http://127.0.0.1:3001，proxy_read_timeout 60s、proxy_connect_timeout 30s，请求体与请求头原样透传。官方注释解释了为什么要经 Nginx 而不是浏览器直连代理：Nginx 的 $arg_* 变量不做 URL 解码，直转会报 "invalid URL prefix"，由 Node 侧用 URLSearchParams 解码才可靠。

SPA 兜底段：try_files $uri $uri/ /index.html——前端路由刷新直达任意路径都回落到 index.html。

请求体上限（重点实测）：整份配置没有 client_max_body_size 指令，Nginx 对 http 级别默认 1 MB 生效。生成 2 MB 测试体经代理上传验证：

dd if=/dev/zero of=big2m.bin bs=1M count=2 2>/dev/null   # 生成 2 MB 测试文件
curl -s -X PUT --data-binary @big2m.bin "http://localhost:8131/api/webdav-proxy/?url=http%3A%2F%2F10.89.59.2%2Fhello.txt"

实测回显（Nginx 在请求进入代理前直接拦截）：

<html>
<head><title>413 Request Entity Too Large</title></head>
<body>
<center><h1>413 Request Entity Too Large</h1></center>
<hr><center>nginx/1.31.7</center>
</body>
</html>

错误日志同步记录（docker compose logs dayglance | grep "too large"）：

2026/10/23 00:40:03 [error] 11#11: *97 client intended to send too large body: 2097152 bytes, client: 10.89.59.1, server: localhost, request: "PUT /api/webdav-proxy/?url=http%3A%2F%2F10.89.59.2%2Fhello.txt HTTP/1.1", host: "localhost:8131"

💡 说明：dayGLANCE 的同步内容是纯文本任务记录（JSON），正常远小于 1 MB，该上限不影响常规使用；经代理传大附件才会碰到，处置见第七节 Q4。

5.3 同步代理行为参数（逐项）

代理进程由镜像入口脚本 /start.sh 拉起（node /app/docker/proxy-server.mjs & 后台启动，随后 Nginx 前台运行），行为参数全部写死在源码里，只能读、不能通过环境变量调整。

监听地址与端口：server.listen(3001, '127.0.0.1')——只绑本机回环，外部无法绕过 Nginx 直连。验证（实测，实例内监听表）：

tcp        0      0 127.0.0.1:3001          0.0.0.0:*               LISTEN      node
tcp        0      0 0.0.0.0:80              0.0.0.0:*               LISTEN      nginx

路由白名单：仅 /api/webdav-proxy 与 /api/calendar-proxy 两个前缀，其余路径一律空体 404。实测：

curl -s -w "\n[%{http_code}]\n" "http://localhost:8131/api/foo"

[404]

目标参数：?url= 缺失返回 400 JSON（实测）：

curl -s -w "\n代理缺参 HTTP %{http_code}\n" "http://localhost:8131/api/webdav-proxy/"

{"error":"Missing url parameter"}
代理缺参 HTTP 400

方法与 CORS：WebDAV 路由声明放行 GET, PUT, DELETE, MKCOL, PROPFIND, OPTIONS，OPTIONS 预检直接返回 204 与全套 CORS 头（实测回显见 5.2 安全头验证）；日历路由只处理 GET。

鉴权透传：WebDAV 路由把请求头 X-WebDAV-Auth 的值原样转成目标站点的 Authorization 头；日历路由同理用 X-Calendar-Auth。用带 Basic 认证的假目标（admin / q1w2e3r4）实测全链路——不带凭据访问受保护路径，目标站的 401 原样中继回来：

401 Unauthorized

[401]

带上 X-WebDAV-Auth 后通过：

curl -s -w "\n[%{http_code}]\n" -H 'X-WebDAV-Auth: Basic YWRtaW46cTF3MmUzcjQ=' "http://localhost:8131/api/webdav-proxy/?url=http%3A%2F%2F10.89.59.4%3A8085%2Fprotected%2Fhello.txt"

secret behind auth
[200]

用假目标的 /echo-auth 端点回显服务端实际收到的头，确认透传的是标准 Authorization：

{"received":"Basic YWRtaW46cTF3MmUzcjQ="}

日历路由同样验证（不带凭据 401；带 X-Calendar-Auth 拿到 ICS 订阅内容 200）：

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//AuthTest//EN
BEGIN:VEVENT
UID:auth-1@t
DTSTART:20261023T120000Z
SUMMARY:Private ICS via auth
END:VEVENT
END:VCALENDAR

[200]

缓存策略（两类路由不同，均实测）：WebDAV 响应 Cache-Control: no-store（同步数据绝不缓存）；日历响应 Cache-Control: public, max-age=900, stale-while-revalidate=60（订阅日历允许 15 分钟新鲜窗口 + 60 秒过期兜底——日历内容变化频率低，缓存能显著减少对日历服务器的轮询）。实测响应头：

HTTP/1.1 200 OK
Content-Type: text/plain
Cache-Control: public, max-age=900, stale-while-revalidate=60
X-Content-Type-Options: nosniff

错误出口：上游连不上返回 502 JSON（实测，目标 10.89.58.99 无服务）：

{"error":"Failed to proxy WebDAV request"}
[502]

5.4 SSRF 网段策略参数

网段判定在 /app/api/_ssrfGuard.mjs，与官方托管版（Vercel Serverless）共用同一策略模块。两档策略的完整清单（源码逐行注释照抄）：

一律拒绝（无论 WEBDAV_PROXY_BLOCK_PRIVATE 取值）——IPv4：

IPv6 侧：fe80::/10（link-local）归入"一律拒绝"，fc00::/7（unique-local）归入"私网"。源码还特别处理了 IPv4-mapped 形式（::ffff:169.254.169.254 绕不过）与编码变形的 IPv4 字面量（WHATWG URL 解析器规范化）。源码注释明确了原因：169.254.169.254 会向任何能触达的人发放云实例凭据，所以无论开关一律拒绝（实测 403 见 5.1）。

私网/局域网（默认放行，设封锁变量后拒绝）——IPv4：10.0.0.0/8、172.16.0.0/12、192.168.0.0/16（RFC 1918 全部三段）、127.0.0.0/8（loopback）、100.64.0.0/10（RFC 6598 CGNAT，Tailscale 网段）。

⚠️ 注意：127.0.0.1 属于"私网"档而非"一律拒绝"档——未设封锁变量时，理论上可以把同步目标指向实例自身回环。这也是官方强调不要把实例裸暴露公网的原因之一：代理是无鉴权中继，务必前置带认证的反向代理（见第六节模板 A）。

5.5 浏览器内应用设置

应用侧全部状态存在浏览器 localStorage（官方口径：服务器无状态），设置项在 Settings 界面修改、即时生效。对实测实例的完整键位盘点（134 个键，2026-10-23 从运行实例的静态产物与 DevTools 取得）如下：

云同步（Settings → Cloud Sync）——配置存在 day-planner-cloud-sync-config 键。表单字段（从应用源码提取的原始定义）：

相关键还有 day-planner-cloud-sync-last-synced（上次同步时间）、day-planner-sync-url、day-planner-sync-retention-days（远端保留天数）、webdavSalt（加密盐）。

同步加密：开启后走 WebCrypto——密钥经 PBKDF2（SHA-256，310000 次迭代） 派生，数据用 AES-GCM 加密（源码常量 iterations:31e4、"AES-GCM"，实测从应用产物中提取）。密钥不出设备，服务器/网盘侧只见密文。

自动备份（Settings → Backup）——配置存在 day-planner-auto-backup-config：频率三档 hourly / daily / weekly（源码选项原文），远端保留策略默认 Daily (keep 30)（每日快照保留 30 份）；执行痕迹记在 day-planner-auto-backup-remote-last / auto-backup-local-last。

日历订阅——day-planner-ics-calendars（订阅列表）、day-planner-task-calendar-url + day-planner-task-calendar-auth（任务日历 URL 与凭据，凭据最终经 5.3 节的 X-Calendar-Auth 通道透传）。

集成：day-planner-obsidian-config（Obsidian 库路径与任务插件约定）、day-planner-trmnl-config（TRMNL 电子墨水屏同步）、dayglance-intent-config（系统集成意图）。

偏好与多用户：day-planner-home-timezone（主时区）、day-planner-week-start-day（周起始日）、day-planner-use-24h-clock（24 小时制）、day-planner-darkmode（深色模式）、day-planner-weather-zip + day-planner-weather-temp-unit（天气）、dayglance-multi-user-enabled + dayglance-users（单机多用户）。

💡 说明：这层的"参数修改"都在界面点选，无需命令行；要点只有一个——它们跟着浏览器走。换浏览器/换设备后设置与数据都从零开始，唯一搬运方式是配置同一个云同步目标（或在浏览器间迁移 localStorage）。

六、生产配置模板

两套按场景给全参数的模板，复制即用。

模板 A：公网域名部署（VPS + 反向代理）

适用场景：1 GB 内存以上的 VPS、有域名、要 HTTPS 与通知功能。磁盘占用约 200 MB（镜像），无数据库。

name: dayglance

services:
  dayglance:
    image: ghcr.io/krelltunez/dayglance:latest
    container_name: dayglance
    restart: unless-stopped
    environment:
      - WEBDAV_PROXY_BLOCK_PRIVATE=1
    ports:
      - "127.0.0.1:6767:80"

逐项说明：environment 开启私网封锁——公网实例可能被陌生人触达，必须掐断"借道代理进内网"的通道；ports 绑 127.0.0.1 只让本机反代能回源，杜绝绕过 TLS 直连。前置 Caddy 反代（HTTPS 自动签发）：

dayglance.yourdomain.com {
    reverse_proxy localhost:6767
}

部署后验证（实测口径）：curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:6767/ 返回 200；再抽一条私网目标确认封锁生效：

curl -s -w "\n[%{http_code}]\n" "http://127.0.0.1:6767/api/webdav-proxy/?url=http%3A%2F%2F10.89.59.2%2Fhello.txt"

{"error":"Private/reserved addresses are not allowed"}
[403]

模板 B：家庭内网 NAS 部署

适用场景：家庭内网/Tailscale 内使用、无需域名与 TLS。磁盘占用同上，内存实测空载约 43 MB。

name: dayglance

services:
  dayglance:
    image: ghcr.io/krelltunez/dayglance:latest
    container_name: dayglance
    restart: unless-stopped
    ports:
      - "6767:80"

不设置封锁变量（保持默认放行），同步目标可以直接指向 NAS 的 WebDAV（如 http://192.168.1.10:5005/）与内网 CalDAV 日历；数据备份靠应用内 Cloud Sync 写向 NAS，配合 hourly 自动备份。若实例同时暴露给访客网络，请改用模板 A 的封锁写法。

七、常见问题

Q1：设置了 WEBDAV_PROXY_BLOCK_PRIVATE=TRUE 却没生效？ 取值是精确匹配，只有 1 和小写 true 有效（实测四态见 5.1 节）。改成小写 true 或 1，并重建实例。

Q2：改了环境变量/端口怎么生效？ 服务端参数在实例启动时读取。compose 场景改完 docker-compose.yml 后执行 docker compose up -d，实例会重建（中断约 5 秒）；源码自建场景重启对应服务（Nginx systemctl reload nginx、代理 systemctl restart dayglance-proxy，每条命令针对一个单元）。

Q3：怎么确认我的实例当前是"放行"还是"封锁"？ 一条命令见分晓：向私网假目标发一次代理请求，返回 200 即放行态、403 即封锁态（两组实测回显见 5.1 节）。

Q4：同步上传报 413？ 实例内置 Nginx 沿用默认 1 MB 请求体上限（实测 2 MB 被拒，见 5.2 节）。任务记录正常远小于 1 MB；若前面自加了反向代理，注意反代层同样默认 1 MB，需同步放开。

Q5：升级后页面还是旧版本？ PWA 的 Service Worker 缓存激进。浏览器强制刷新（Ctrl+Shift+R / Cmd+Shift+R）清除即可；镜像已把 sw.js 列为不缓存（5.2 节），正常升级链路不会卡住。

Q6：想往页面里加第三方脚本/统计被拦？ CSP 的 script-src 'self' 'unsafe-inline' 只放行同源与内联脚本（5.2 节），第三方脚本按设计被拦。自建形态（方案 A）持有自己的 Nginx 配置，可自行调整 CSP，官方镜像不改。

Q7：能挂在 example.com/dayglance 子路径下吗？ 不支持。官方自托管文档明确：所有资源路径与内部 API 调用都是根绝对路径，必须部署在域名/子域名根（2026-10-22 查询官方文档）。

八、参考链接

• 官方自托管文档：https://docs.dayglance.app/self-hosting
• 官方云同步文档：https://docs.dayglance.app/en/cloud-sync
• 官方日历导入文档：https://docs.dayglance.app/en/calendar-import
• 源码策略模块（SSRF 守卫）：https://github.com/krelltunez/dayGLANCE/blob/main/api/_ssrfGuard.mjs
• 本专栏配套文章：软件定位与选型见 《dayGLANCE 5.9.0 介绍与选型指南》；非容器化安装见 《Ubuntu 22.04 安装 dayGLANCE 5.9.0 指南》；容器化部署与运维命令见 《dayGLANCE 5.9.0 Docker Compose 部署指南》；代理接口逐条调用实测见 《dayGLANCE 5.9.0 API 使用详解》