Skip to content

docs(npm): add optional advanced config section for performance and security - #579

Merged
f2c-ci-robot[bot] merged 2 commits into
halo-dev:mainfrom
Lau0x:docs/npm-advanced-config
Apr 20, 2026
Merged

f2c-ci-robot[bot] merged 2 commits into
halo-dev:mainfrom
Lau0x:docs/npm-advanced-config

Conversation

@Lau0x

@Lau0x Lau0x commented Apr 20, 2026 •

Copy link
Copy Markdown
Contributor

背景

当前 Nginx Proxy Manager 反向代理 文档很好地覆盖了基础场景(添加代理记录、申请 SSL),但对一些用户在生产环境会遇到的两个常见问题没有展开:

  1. NPM 默认的 gzip_types 只压 HTML/CSS,JavaScript、字体、JSON 等静态资源未启用 gzip。例如一个 ~90 KB 的主题 JS 文件,gzip 后大约 25–30 KB,差距明显。
  2. 默认反代只给出最基础的响应头,没有常规安全响应头(X-Frame-Options、Referrer-Policy、Permissions-Policy 等)。用 securityheaders.com 扫描时评级为 D–F。

本 PR 将这些通用优化以可选小节的形式补入现有文档,帮助用户通过 NPM 的 Advanced → Custom Nginx Configuration 一次性启用。

本 PR 做了什么

在现有文档末尾追加 ## 进阶配置:性能与安全(可选) 一节,不改动任何现有内容(diff 是纯追加 +116 行)。内容包括:

  • 进入路径说明:NPM 仪表盘 → Hosts → Proxy Hosts → 编辑 → Advanced → Custom Nginx Configuration
  • 完整的 Custom Nginx Configuration 配置块,含注释:
    • gzip_types 补齐 JS / 字体 / JSON / SVG / atom+rss 等 MIME 类型,加 gzip_static on
    • proxy_buffers 16 32k + proxy_buffer_size 64k 避免较大响应临时落盘
    • 5 个常规安全头(X-Content-Type-Options / X-Frame-Options / X-XSS-Protection / Referrer-Policy / Permissions-Policy),均带 `always` 保证错误页也返回
    • RSS 路径别名:`/rss` 与 `/feed` 301 跳转到 Halo 默认的 `/rss.xml`
    • HSTS 以注释形式给出,并在下方单独说明
  • HSTS 单独说明段:强调从短 `max-age` 起步、谨慎对待 `preload`(提交后撤销困难)
  • 验证命令(curl + DevTools)
  • FAQ × 3:
    • 能拿到 securityheaders.com A+ 吗?(A 已足够,追 A+ 涉及 CSP,给出 Report-Only → 白名单收敛 → 生产 CSP 的务实路径)
    • NPM 界面「缓存资源」开关要开启吗?(不建议,与现有文档一致,补充了原因)
    • 为什么要调大 proxy buffer?(解释 nginx 落盘行为)

设计原则

  • 通用性:所有配置都是反代层优化,不依赖特定主题,任何 Halo 实例都适用
  • 非侵入:独立成节,标明「可选」,不改现有基础教程,老读者阅读路径不受影响
  • 保守默认:HSTS 默认注释掉、`preload` 仅在说明段提到风险后才建议;CSP 不直接给配置、只给务实的落地路径
  • 与既有建议一致:保留并强化了现文档对「缓存资源不建议打开」的建议,并补充了技术原因

实践验证

配置在生产环境 Halo 博客上验证过:

  • JavaScript 响应头出现 `content-encoding: gzip`,主题资源传输体积明显下降
  • securityheaders.com 扫描从默认配置提升到 A 评级
  • HSTS 按文档建议从 `max-age=300` 起步验证再调大,未出现 HTTPS→HTTP 回退故障

兼容性

  • 纯新增可选小节,不影响已有部署
  • 所有 nginx 指令为标准指令,兼容 NPM 自 2020 年后任意版本
  • 不涉及 Halo 端配置变更

欢迎 review,如有任何调整建议随时指出。

None

…ecurity

在 Nginx Proxy Manager 反代文档末尾追加「进阶配置:性能与安全(可选)」小节,
补全 NPM 默认未覆盖的优化与响应头,所有配置均为反代层通用、与具体主题无关。

内容包括:
- gzip 配置补齐 JS、字体、JSON 等 MIME 类型(解决 NPM 默认只压 HTML/CSS 问题)
- proxy_buffers 调大避免较大响应落盘
- 5 个主流安全响应头(X-Content-Type-Options / X-Frame-Options / X-XSS-Protection /
  Referrer-Policy / Permissions-Policy),带 always 确保错误页也返回
- HSTS 单独说明:先短 max-age 验证再逐步调大,preload 提交需谨慎
- RSS 路径别名:/rss 与 /feed 301 跳转到 /rss.xml
- 验证命令(curl + DevTools)
- FAQ:A+/CSP 路径、NPM 缓存开关建议、proxy buffer 的作用

现有基础教程内容未改动。
@f2c-ci-robot f2c-ci-robot Bot added do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. release-note-none Denotes a PR that doesn't merit a release note. and removed do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. labels Apr 20, 2026

@ruibaby ruibaby left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/lgtm

@f2c-ci-robot f2c-ci-robot Bot added the lgtm Indicates that a PR is ready to be merged. label Apr 20, 2026
@f2c-ci-robot

f2c-ci-robot Bot commented Apr 20, 2026

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: ruibaby

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@f2c-ci-robot f2c-ci-robot Bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Apr 20, 2026
@f2c-ci-robot
f2c-ci-robot Bot merged commit 6c6733e into halo-dev:main Apr 20, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. lgtm Indicates that a PR is ready to be merged. release-note-none Denotes a PR that doesn't merit a release note.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants