docnest 0.1.12 → 0.1.13

package/README.md

@@ -78,6 +78,8 @@ export default defineConfig({
   auth: {
     enabled: true,
     passphrase: '请替换为项目自己的长口令',
+    // 服务通过反向代理挂载在子路径时填写，例如 /documents；默认跳转到 /。
+    redirectPrefix: '',
     stateFile: '.docnest/auth.json',
     localStorageKey: 'my-project:auth-passphrase',
     sessionTtlMinutes: 24 * 60,
@@ -91,6 +93,8 @@ export default defineConfig({
 `localStorageKey` 可选，用于为不同宿主项目隔离浏览器存储键。内置授权不提供“修改口令”或“退出”按钮；需要更换口令时，停止服务、删除 `stateFile`，修改配置中的 `passphrase` 后重新启动。
 建议把 `.docnest/` 加入宿主项目的 `.gitignore`，并为口令状态文件设置仅当前用户可读写的权限。
 
+如果 DocNest 由反向代理挂载在 `/documents/` 等子路径下，将 `auth.redirectPrefix` 配置为 `/documents`。登录页会把原始文档目标写成带此前缀的路径，口令登录后的服务端跳转也会使用同一前缀；不配置时保持跳转到 `/` 的默认行为。
+
 授权开启但既没有状态文件，也没有初始 `passphrase` 时，DocNest 会拒绝启动，避免意外以空口令开放文档。
 
 如需显式指定端口、文档目录或监听地址：
@@ -136,3 +140,16 @@ npm run pack:check
 ```
 
 最低支持 Node.js 20，验证 Node.js 20 和 22。
+
+## 发布规范
+
+DocNest 的 GitHub Release 和 npm 发布统一由 GitHub Actions 完成，不在本地直接执行 `npm publish`。
+
+发布新版本时：
+
+1. 更新 `package.json` 和 `package-lock.json` 的版本号，并运行 `npm test` 与 `npm run pack:check`。
+2. 将版本提交推送到 `main`。
+3. 在 `main` 上创建与包版本一致的标签，例如 `v0.1.13`。
+4. 推送该标签：`git push origin v0.1.13`。
+
+标签推送后，`.github/workflows/publish.yml` 会校验标签与包版本一致，使用 npm OIDC 发布公开包，并自动创建名为 `DocNest v0.1.13` 的 GitHub Release。远程仓库只保留 `main` 分支，发布标签不需要推送临时开发分支。

package/dist/config.d.ts

@@ -28,6 +28,11 @@ export type DocNestConfig = {
     auth?: {
         enabled?: boolean;
         passphrase?: string;
+        /**
+         * Prefix to add to authentication return targets when the service is
+         * mounted below a reverse-proxy path, for example `/documents`.
+         */
+        redirectPrefix?: string;
         stateFile?: string;
         localStorageKey?: string;
         sessionTtlMinutes?: number;
@@ -49,6 +54,7 @@ export type ResolvedDocNestConfig = Required<DocNestConfig> & {
     auth: {
         enabled: boolean;
         passphrase: string;
+        redirectPrefix: string;
         stateFile: string;
         localStorageKey: string;
         sessionTtlMinutes: number;

package/dist/config.js

@@ -45,6 +45,20 @@ function normalizePositiveNumber(value, fallback) {
     const normalized = Number(value);
     return Number.isFinite(normalized) && normalized > 0 ? normalized : fallback;
 }
+function normalizeRedirectPrefix(value) {
+    if (typeof value !== 'string')
+        return '';
+    const normalized = value.trim();
+    if (!normalized ||
+        normalized === '/' ||
+        !normalized.startsWith('/') ||
+        normalized.startsWith('//') ||
+        normalized.includes('//') ||
+        normalized.includes('\\') ||
+        /[\r\n?#]/.test(normalized))
+        return '';
+    return normalized.replace(/\/+$/, '') || '';
+}
 function normalizeThemeName(value) {
     if (value === 'current-docs')
         return 'slate-modern';
@@ -113,6 +127,7 @@ async function loadConfig(projectRoot = process.cwd()) {
         auth: {
             enabled: auth.enabled ?? false,
             passphrase: typeof auth.passphrase === 'string' ? auth.passphrase : '',
+            redirectPrefix: normalizeRedirectPrefix(auth.redirectPrefix),
             stateFile: node_path_1.default.resolve(projectRoot, auth.stateFile?.trim() || '.docnest/auth.json'),
             localStorageKey: authLocalStorageKey,
             sessionTtlMinutes: normalizePositiveNumber(auth.sessionTtlMinutes, 24 * 60),

package/dist/server.js

@@ -280,6 +280,17 @@ function safeNextPath(value) {
         return '/';
     return value;
 }
+function authRedirectTarget(value) {
+    const nextPath = safeNextPath(value);
+    const prefix = typeof AUTH_CONFIG.redirectPrefix === 'string' ? AUTH_CONFIG.redirectPrefix : '';
+    if (!prefix ||
+        nextPath === prefix ||
+        nextPath.startsWith(`${prefix}/`) ||
+        nextPath.startsWith(`${prefix}?`) ||
+        nextPath.startsWith(`${prefix}#`))
+        return nextPath;
+    return nextPath === '/' ? `${prefix}/` : `${prefix}${nextPath}`;
+}
 function setAuthCookie(res, token) {
     const maxAge = AUTH_MANAGER.sessionMaxAgeSeconds;
     res.setHeader('Set-Cookie', `${AUTH_MANAGER.sessionCookieName}=${encodeURIComponent(token)}; Max-Age=${maxAge}; Path=/; HttpOnly; SameSite=Lax`);
@@ -292,7 +303,7 @@ function wantsJson(req) {
 }
 function renderLoginPage(res, nextPath, error, status = 200) {
     return res.status(status).render('login', {
-        nextPath: safeNextPath(nextPath),
+        nextPath: authRedirectTarget(nextPath),
         error: error || '',
         assetVersion: ASSET_VERSION,
     });
@@ -316,7 +327,7 @@ app.post('/auth/verify', (req, res) => {
 app.post('/auth/login', (req, res) => {
     if (!BUILT_IN_AUTH_ENABLED)
         return res.redirect('/');
-    const nextPath = safeNextPath(req.body?.next);
+    const nextPath = authRedirectTarget(req.body?.next);
     const token = AUTH_MANAGER.createSession(String(req.body?.passphrase || ''));
     if (!token)
         return renderLoginPage(res, nextPath, '口令不正确，请重试。', 401);

package/docnest.config.example.mjs

@@ -36,6 +36,8 @@ export default defineConfig({
     enabled: false,
     // 仅首次启动且授权状态文件不存在时使用；更换口令需手动删除状态文件后重启。
     passphrase: '',
+    // 通过反向代理挂载在子路径时，为登录成功后的目标补此前缀；默认空值跳转到根路径。
+    redirectPrefix: '',
     stateFile: '.docnest/auth.json',
     // 前端 localStorage 的键；口令会永久保存在浏览器本地，直到手动清除或口令失效。
     localStorageKey: 'my-project:auth-passphrase',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docnest",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "可复用的本地 Markdown 文档中心",
   "repository": {
     "type": "git",