isr-engine 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -617
- package/dist/app/createISRApp.d.ts +2 -2
- package/dist/cli/cli.cjs +1 -1
- package/dist/cli/cli.js +1 -1
- package/dist/cli/start.d.ts +1 -1
- package/dist/config/loadConfig.d.ts +1 -1
- package/dist/config/normalizeEngineConfig.d.ts +1 -1
- package/dist/config/resolveRuntimeRedis.d.ts +1 -1
- package/dist/{createCacheInspectorMiddleware-CAzxgGNh.cjs → createCacheInspectorMiddleware-DGSjHQJd.cjs} +2 -2
- package/dist/{createCacheInspectorMiddleware-CAzxgGNh.cjs.map → createCacheInspectorMiddleware-DGSjHQJd.cjs.map} +1 -1
- package/dist/{createCacheInspectorMiddleware-B32Suct_.js → createCacheInspectorMiddleware-Dmuobpcb.js} +2 -2
- package/dist/{createCacheInspectorMiddleware-B32Suct_.js.map → createCacheInspectorMiddleware-Dmuobpcb.js.map} +1 -1
- package/dist/{createISRApp-CfGFTcw-.js → createISRApp-CDkyUuW3.js} +17 -18
- package/dist/createISRApp-CDkyUuW3.js.map +1 -0
- package/dist/{createISRApp-Bvs5_63N.cjs → createISRApp-Nv9mwX8I.cjs} +17 -18
- package/dist/createISRApp-Nv9mwX8I.cjs.map +1 -0
- package/dist/{createImagePlugin-BHVUkFBd.js → createImagePlugin-BVUPlPOz.js} +2 -2
- package/dist/{createImagePlugin-BHVUkFBd.js.map → createImagePlugin-BVUPlPOz.js.map} +1 -1
- package/dist/{createImagePlugin-C-hHZCqj.cjs → createImagePlugin-D-X_HGlR.cjs} +2 -2
- package/dist/{createImagePlugin-C-hHZCqj.cjs.map → createImagePlugin-D-X_HGlR.cjs.map} +1 -1
- package/dist/defaults/runtime/browserObservability.d.ts.map +1 -1
- package/dist/defaults/runtime/dev-style-resource-dispatcher.server.d.ts.map +1 -1
- package/dist/engine/ISREngine.d.ts +2 -2
- package/dist/index.d.ts +3 -3
- package/dist/isr/ISRRoutes.d.ts +3 -3
- package/dist/isr-engine.cjs +2 -2
- package/dist/isr-engine.cjs.map +1 -1
- package/dist/isr-engine.js +2 -2
- package/dist/isr-engine.js.map +1 -1
- package/dist/server/manager.d.ts +1 -1
- package/dist/server/opsConfig.d.ts +1 -1
- package/dist/server/productionRuntime.d.ts +2 -2
- package/dist/server/productionRuntime.d.ts.map +1 -1
- package/dist/server/types.d.ts +1 -1
- package/dist/ssg/spider.d.ts.map +1 -1
- package/dist/types/ISRConfig.d.ts.map +1 -1
- package/dist/utils/resolveFetchHandler.d.ts.map +1 -1
- package/package.json +13 -14
- package/src/defaults/runtime/browserObservability.ts +2 -4
- package/src/defaults/runtime/dev-style-resource-dispatcher.server.ts +1 -2
- package/src/types/ISRConfig.ts +2 -7
- package/src/utils/resolveFetchHandler.ts +1 -3
- package/dist/createISRApp-Bvs5_63N.cjs.map +0 -1
- package/dist/createISRApp-CfGFTcw-.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,695 +1,171 @@
|
|
|
1
|
-
#
|
|
1
|
+
# isr-engine
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
基于 Vite 与 React Server Components 的页面渲染编排层,提供按路由配置的 ISR、SSG、SSR、缓存失效和渲染失败恢复。Flight 编译与传输由 `@vitejs/plugin-rsc` 处理。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## 运行要求与安装
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
- Node.js **24.15.0**;仓库使用 pnpm 9.15.9。
|
|
8
|
+
- Vite **8.1.6**;内置 `@vitejs/plugin-rsc` **0.5.34**,无需额外注册 React 插件。
|
|
9
|
+
- `react`、`react-dom`、`react-server-dom-webpack` 必须同为 **19.3.0-canary-bd6ea412-20260824**。当前支持该精确 canary 组合。
|
|
10
|
+
- `rsc-html-stream` peer 范围为 `^0.0.7`,仓库锁定版本为 **0.0.7**。
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
> 包名前缀 `@novel-isr` 仅是首发项目代号,与小说业务**无任何耦合**——
|
|
14
|
-
> grep 全仓源码无业务硬编码,运行时无业务假设。发到 GitHub Packages
|
|
15
|
-
> (restricted),不发 public registry;项目仍处于 **alpha** 阶段(详见末尾「生产可用性诚实评估」)。
|
|
16
|
-
|
|
17
|
-
## 30 秒看明白
|
|
12
|
+
在应用目录安装公共 npm 包及其 peer 依赖:
|
|
18
13
|
|
|
19
14
|
```bash
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
pnpm add @novel-isr/engine@^2.6.2 \
|
|
15
|
+
npm install isr-engine --registry=https://registry.npmjs.org/
|
|
16
|
+
npm install --save-exact \
|
|
23
17
|
react@19.3.0-canary-bd6ea412-20260824 \
|
|
24
18
|
react-dom@19.3.0-canary-bd6ea412-20260824 \
|
|
25
19
|
react-server-dom-webpack@19.3.0-canary-bd6ea412-20260824 \
|
|
26
|
-
rsc-html-stream
|
|
27
|
-
|
|
20
|
+
rsc-html-stream@0.0.7
|
|
21
|
+
npm install --save-dev --save-exact vite@8.1.6 typescript@5.9.3 \
|
|
22
|
+
@types/node@24.19.2 @types/react@19.2.15 @types/react-dom@19.2.3
|
|
28
23
|
```
|
|
29
24
|
|
|
30
|
-
|
|
25
|
+
应用 `package.json` 设置 `"type": "module"`,并保留锁文件以复现依赖组合。
|
|
26
|
+
|
|
27
|
+
## 最小应用
|
|
31
28
|
|
|
32
|
-
|
|
29
|
+
`vite.config.ts`:
|
|
33
30
|
|
|
34
31
|
```ts
|
|
35
|
-
// vite.config.ts
|
|
36
32
|
import { defineConfig } from 'vite';
|
|
37
|
-
import { createIsrPlugin } from '
|
|
38
|
-
export default defineConfig({ plugins: [...createIsrPlugin()] });
|
|
39
|
-
```
|
|
33
|
+
import { createIsrPlugin } from 'isr-engine';
|
|
40
34
|
|
|
41
|
-
|
|
42
|
-
// package.json
|
|
43
|
-
{
|
|
44
|
-
"scripts": {
|
|
45
|
-
"dev": "novel-isr dev",
|
|
46
|
-
"build": "vite build",
|
|
47
|
-
"start": "novel-isr start"
|
|
48
|
-
}
|
|
49
|
-
}
|
|
35
|
+
export default defineConfig({ plugins: [...createIsrPlugin()] });
|
|
50
36
|
```
|
|
51
37
|
|
|
52
|
-
|
|
53
|
-
// src/routes.tsx —— 业务唯一路由源;SSR/ISR/SSG/CSR recovery 都复用这一份
|
|
54
|
-
import { defineRoutes } from '@novel-isr/engine/runtime';
|
|
55
|
-
|
|
56
|
-
export const { routes } = defineRoutes({
|
|
57
|
-
notFound: { load: () => import('./pages/NotFoundPage') },
|
|
58
|
-
routes: [
|
|
59
|
-
{ path: '/', load: () => import('./pages/HomePage') },
|
|
60
|
-
{ path: '/books/:id', load: () => import('./pages/BookDetailPage') },
|
|
61
|
-
{ path: '/about', load: () => import('./pages/AboutPage') },
|
|
62
|
-
],
|
|
63
|
-
});
|
|
64
|
-
```
|
|
38
|
+
`src/app.tsx` 是应用根 Server Component,必须命名导出 `App`。交互组件单独使用 `'use client'`:
|
|
65
39
|
|
|
66
40
|
```tsx
|
|
67
|
-
|
|
68
|
-
import { parseLocale, resolveI18nConfig } from '@novel-isr/engine/runtime';
|
|
69
|
-
import siteHooks from './entry.server';
|
|
70
|
-
import { routes } from './routes';
|
|
71
|
-
|
|
72
|
-
const I18N = resolveI18nConfig(siteHooks.intl);
|
|
41
|
+
import { cacheTag } from 'isr-engine/rsc';
|
|
73
42
|
|
|
74
43
|
export function App({ url }: { url: URL }) {
|
|
75
|
-
|
|
44
|
+
cacheTag('site-content');
|
|
76
45
|
return (
|
|
77
|
-
<html lang=
|
|
78
|
-
<
|
|
46
|
+
<html lang="zh-CN">
|
|
47
|
+
<head><meta charSet="utf-8" /><title>My site</title></head>
|
|
48
|
+
<body><main><h1>{url.pathname}</h1></main></body>
|
|
79
49
|
</html>
|
|
80
50
|
);
|
|
81
51
|
}
|
|
82
52
|
```
|
|
83
53
|
|
|
54
|
+
项目根目录的 `ssr.config.ts` 声明渲染策略与部署配置:
|
|
55
|
+
|
|
84
56
|
```ts
|
|
85
|
-
|
|
86
|
-
import { defineIsrConfig } from '@novel-isr/engine/config';
|
|
87
|
-
import fallbackLocal from './src/config/site-fallback-local.json';
|
|
57
|
+
import { defineIsrConfig } from 'isr-engine/config';
|
|
88
58
|
|
|
89
59
|
export default defineIsrConfig({
|
|
90
60
|
renderMode: 'isr',
|
|
91
|
-
|
|
92
|
-
site: process.env.SITE_URL ?? 'http://localhost:3000',
|
|
93
|
-
services: {
|
|
94
|
-
api: process.env.API_URL ?? 'http://localhost:8080',
|
|
95
|
-
telemetry: process.env.TELEMETRY_API_URL ?? process.env.API_URL ?? 'http://localhost:8080',
|
|
96
|
-
},
|
|
97
|
-
redis: {
|
|
98
|
-
url: process.env.REDIS_URL,
|
|
99
|
-
host: undefined,
|
|
100
|
-
port: undefined,
|
|
101
|
-
password: undefined,
|
|
102
|
-
keyPrefix: 'isr:',
|
|
103
|
-
invalidationChannel: 'isr:invalidate',
|
|
104
|
-
},
|
|
105
|
-
telemetry: {
|
|
106
|
-
app: 'novel-rating',
|
|
107
|
-
release: process.env.APP_VERSION,
|
|
108
|
-
environment: process.env.NODE_ENV,
|
|
109
|
-
includeQueryString: false,
|
|
110
|
-
events: {
|
|
111
|
-
endpoint: '/api/observability/analytics',
|
|
112
|
-
trackInitialPage: true,
|
|
113
|
-
sampleRate: 1,
|
|
114
|
-
batchSize: 20,
|
|
115
|
-
flushIntervalMs: 3000,
|
|
116
|
-
maxQueueSize: 500,
|
|
117
|
-
retryBaseDelayMs: 1000,
|
|
118
|
-
retryMaxDelayMs: 30000,
|
|
119
|
-
},
|
|
120
|
-
errors: {
|
|
121
|
-
endpoint: '/api/observability/errors',
|
|
122
|
-
captureResourceErrors: true,
|
|
123
|
-
sampleRate: 1,
|
|
124
|
-
batchSize: 10,
|
|
125
|
-
flushIntervalMs: 3000,
|
|
126
|
-
maxQueueSize: 200,
|
|
127
|
-
retryBaseDelayMs: 1000,
|
|
128
|
-
retryMaxDelayMs: 30000,
|
|
129
|
-
},
|
|
130
|
-
webVitals: { enabled: true },
|
|
131
|
-
exporters: [],
|
|
132
|
-
integrations: {
|
|
133
|
-
sentry: {
|
|
134
|
-
enabled: process.env.SENTRY_ENABLED === 'true',
|
|
135
|
-
dsn: process.env.SENTRY_DSN,
|
|
136
|
-
tracesSampleRate: 0.1,
|
|
137
|
-
environment: process.env.NODE_ENV,
|
|
138
|
-
release: process.env.APP_VERSION,
|
|
139
|
-
},
|
|
140
|
-
},
|
|
141
|
-
},
|
|
142
|
-
experiments: {
|
|
143
|
-
'hero-style': { variants: ['classic', 'bold'], weights: [50, 50] },
|
|
144
|
-
},
|
|
145
|
-
i18n: {
|
|
146
|
-
locales: fallbackLocal.site.locales,
|
|
147
|
-
defaultLocale: fallbackLocal.site.defaultLocale,
|
|
148
|
-
prefixDefault: false,
|
|
149
|
-
endpoint: '/api/i18n/{locale}/manifest',
|
|
150
|
-
fallbackLocal: fallbackLocal.i18n.strings,
|
|
151
|
-
ttl: 60_000,
|
|
152
|
-
timeoutMs: 1200,
|
|
153
|
-
remoteSource: 'admin-server',
|
|
154
|
-
fallbackSource: 'fallback-local',
|
|
155
|
-
},
|
|
156
|
-
seo: {
|
|
157
|
-
endpoint: '/api/seo?path={pathname}',
|
|
158
|
-
fallbackLocal: fallbackLocal.seo.entries,
|
|
159
|
-
ttl: 60_000,
|
|
160
|
-
timeoutMs: 1200,
|
|
161
|
-
},
|
|
162
|
-
},
|
|
61
|
+
revalidate: 60,
|
|
163
62
|
routes: {
|
|
164
63
|
'/': { mode: 'isr', ttl: 60, staleWhileRevalidate: 300 },
|
|
165
64
|
'/about': 'ssg',
|
|
166
|
-
'/
|
|
167
|
-
|
|
65
|
+
'/account/*': 'ssr',
|
|
66
|
+
},
|
|
67
|
+
runtime: {
|
|
68
|
+
site: process.env.SITE_URL ?? 'http://localhost:3000',
|
|
69
|
+
services: { api: undefined, telemetry: undefined },
|
|
70
|
+
redis: process.env.REDIS_URL ? {
|
|
71
|
+
url: process.env.REDIS_URL,
|
|
72
|
+
host: undefined, port: undefined, password: undefined,
|
|
73
|
+
keyPrefix: 'my-site:', invalidationChannel: 'my-site:invalidate',
|
|
74
|
+
} : undefined,
|
|
75
|
+
experiments: {},
|
|
76
|
+
i18n: undefined, seo: undefined, telemetry: false,
|
|
168
77
|
},
|
|
169
78
|
server: {
|
|
170
79
|
port: Number(process.env.PORT ?? 3000),
|
|
171
80
|
host: process.env.HOST,
|
|
172
|
-
strictPort: process.env.NODE_ENV
|
|
81
|
+
strictPort: process.env.NODE_ENV === 'production',
|
|
173
82
|
ops: {
|
|
174
83
|
authToken: process.env.ISR_OPS_TOKEN,
|
|
175
84
|
tokenHeader: 'x-isr-admin-token',
|
|
176
85
|
health: { enabled: true, public: true },
|
|
177
86
|
metrics: { enabled: process.env.ENABLE_METRICS === '1', public: false },
|
|
87
|
+
inventory: { enabled: true, public: false },
|
|
178
88
|
},
|
|
179
89
|
},
|
|
180
90
|
ssg: {
|
|
181
|
-
routes: ['/about'],
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
maxRetries: 3,
|
|
185
|
-
retryBaseDelayMs: 200,
|
|
186
|
-
failBuildThreshold: 0.05,
|
|
187
|
-
},
|
|
188
|
-
revalidate: 3600,
|
|
189
|
-
});
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
```ts
|
|
193
|
-
// src/entry.server.ts —— 可选:只放请求期 hooks,例如用户、租户、分层、错误上报
|
|
194
|
-
import { defineAdminSiteHooks, readCookie } from '@novel-isr/engine/site-hooks';
|
|
195
|
-
|
|
196
|
-
export default defineAdminSiteHooks({
|
|
197
|
-
beforeRequest: req => ({
|
|
198
|
-
userId: req.headers.get('x-user-id') ?? readCookie(req, 'uid') ?? undefined,
|
|
199
|
-
tenantId: req.headers.get('x-tenant-id') ?? 'public',
|
|
200
|
-
}),
|
|
201
|
-
onError: (err, req, ctx) => {
|
|
202
|
-
console.error('[render error]', { traceId: ctx.traceId, url: req.url, err });
|
|
203
|
-
},
|
|
204
|
-
});
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
`beforeRequest` 返回值会进入当前请求的 `RequestContext`。Server Component 里用
|
|
208
|
-
`getRequestContext()` 读取用户、租户、分群等请求级字段;Client Component 需要由
|
|
209
|
-
Server Component 读取后作为 props 传入。A/B variant 不在 `beforeRequest` 里手写解析,
|
|
210
|
-
页面用 `getVariant()` 读取,engine 负责 sticky cookie 和 ISR variant 缓存隔离。
|
|
211
|
-
完整用法见 [docs/site-hooks.md](./docs/site-hooks.md#beforerequest--onerror)。
|
|
212
|
-
|
|
213
|
-
`pnpm dev` → http://localhost:3000。开发模式会自动注入 **Novel ISR Inspector** 浮层,
|
|
214
|
-
可直接切换/验证 ISR、SSR、SSG、CSR fallback。业务不需要 import 调试组件。
|
|
215
|
-
如需隐藏浮层,新建 `src/entry.tsx`:
|
|
216
|
-
|
|
217
|
-
```ts
|
|
218
|
-
export default {
|
|
219
|
-
devInspector: false,
|
|
220
|
-
};
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
浏览器埋点和错误上报由 engine 按 endpoint 配置注入轻量 runtime,业务不用重写导航监听或全局错误监听,
|
|
224
|
-
也不需要把第三方 SDK import 到 engine。部署期只在 `ssr.config.ts` 配 telemetry endpoint、
|
|
225
|
-
采样、批量策略和 integration:
|
|
226
|
-
|
|
227
|
-
```ts
|
|
228
|
-
// ssr.config.ts
|
|
229
|
-
export default {
|
|
230
|
-
runtime: {
|
|
231
|
-
services: {
|
|
232
|
-
api: process.env.API_URL ?? 'https://admin.example.com',
|
|
233
|
-
telemetry: process.env.TELEMETRY_API_URL ?? 'https://admin.example.com',
|
|
234
|
-
},
|
|
235
|
-
telemetry: {
|
|
236
|
-
app: 'novel-rating',
|
|
237
|
-
release: process.env.APP_VERSION,
|
|
238
|
-
environment: process.env.NODE_ENV,
|
|
239
|
-
includeQueryString: false,
|
|
240
|
-
events: {
|
|
241
|
-
endpoint: '/api/observability/analytics',
|
|
242
|
-
trackInitialPage: true,
|
|
243
|
-
sampleRate: 1,
|
|
244
|
-
batchSize: 20,
|
|
245
|
-
flushIntervalMs: 3000,
|
|
246
|
-
maxQueueSize: 500,
|
|
247
|
-
retryBaseDelayMs: 1000,
|
|
248
|
-
retryMaxDelayMs: 30000,
|
|
249
|
-
},
|
|
250
|
-
errors: {
|
|
251
|
-
endpoint: '/api/observability/errors',
|
|
252
|
-
captureResourceErrors: true,
|
|
253
|
-
sampleRate: 1,
|
|
254
|
-
batchSize: 10,
|
|
255
|
-
flushIntervalMs: 3000,
|
|
256
|
-
maxQueueSize: 200,
|
|
257
|
-
retryBaseDelayMs: 1000,
|
|
258
|
-
retryMaxDelayMs: 30000,
|
|
259
|
-
},
|
|
260
|
-
webVitals: { enabled: true },
|
|
261
|
-
exporters: [],
|
|
262
|
-
integrations: {
|
|
263
|
-
sentry: {
|
|
264
|
-
enabled: process.env.SENTRY_ENABLED === 'true',
|
|
265
|
-
dsn: process.env.SENTRY_DSN,
|
|
266
|
-
tracesSampleRate: 0.1,
|
|
267
|
-
environment: process.env.NODE_ENV,
|
|
268
|
-
release: process.env.APP_VERSION,
|
|
269
|
-
},
|
|
270
|
-
},
|
|
271
|
-
},
|
|
272
|
-
},
|
|
273
|
-
};
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
设计边界:`isr-engine` 不 import 业务 SDK,也不绑定 Sentry/Datadog/自研采集端;
|
|
277
|
-
第一方 HTTP 链路只看 `events.endpoint` / `errors.endpoint`,不再在 exporter 里重复配置同一个地址。
|
|
278
|
-
Sentry 是
|
|
279
|
-
`runtime.telemetry.integrations.sentry` 里的完整第三方平台集成,不降级成普通 HTTP exporter;
|
|
280
|
-
它可和第一方 endpoint 同时使用,也可通过关闭 `events/errors` 做二选一。
|
|
281
|
-
engine 不做隐式替换,失败不会影响渲染或其它上报。
|
|
282
|
-
`@novel-isr/analytics` 和 `@novel-isr/error-reporting`
|
|
283
|
-
是独立 SDK,给非 engine 应用或自定义集成使用。
|
|
284
|
-
完整说明见 [docs/observability.md](./docs/observability.md)。
|
|
285
|
-
|
|
286
|
-
业务显式事件不要写 endpoint 上传逻辑,直接用 engine runtime facade:
|
|
287
|
-
|
|
288
|
-
```ts
|
|
289
|
-
import {
|
|
290
|
-
capture,
|
|
291
|
-
flushTelemetry,
|
|
292
|
-
measure,
|
|
293
|
-
page,
|
|
294
|
-
setTelemetryUser,
|
|
295
|
-
track,
|
|
296
|
-
} from '@novel-isr/engine/runtime';
|
|
297
|
-
|
|
298
|
-
setTelemetryUser({ id: userId, tenantId });
|
|
299
|
-
track('review.submit', { bookId, score }, { tags: { feature: 'reviews' } });
|
|
300
|
-
measure('search.latency', durationMs, { unit: 'ms', tags: { route: '/search' } });
|
|
301
|
-
capture(error, { source: 'rating-widget', extra: { bookId } });
|
|
302
|
-
page('/custom-router/books/1'); // 常规路由不需要,engine 会自动上报 page_view
|
|
303
|
-
await flushTelemetry();
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
这些调用复用 `runtime.telemetry.events/errors` 的同一套队列、采样、重试和 sendBeacon,不需要业务关心 transport。
|
|
307
|
-
API 语义:
|
|
308
|
-
|
|
309
|
-
- `track`:业务事件,例如收藏、评分、搜索提交。
|
|
310
|
-
- `capture`:已知业务失败或组件错误边界,补充 `source/tags/extra/fingerprint`。
|
|
311
|
-
- `measure`:一次原始数值样本,例如请求耗时、队列等待时间、交互延迟。
|
|
312
|
-
- `page`:自定义 router 的页面浏览;普通 `pushState/popstate` 由 engine 自动处理。
|
|
313
|
-
- `setTelemetryUser`:设置后续上报的 user / tenant / segment 上下文。
|
|
314
|
-
- `flushTelemetry`:登出、支付跳转、关闭前主动 flush。
|
|
315
|
-
|
|
316
|
-
`measure()` 只发送一次原始观测值;p95、趋势、慢页面排行和告警阈值应该在后端 /
|
|
317
|
-
dashboard 聚合,不在浏览器里做二级统计。
|
|
318
|
-
Web Vitals / INP 也是同一原则:浏览器只发送 `{ name, value }` 这类事实样本,
|
|
319
|
-
服务端按 route、release、device、tenant 和用户分群计算 p75/p95 与评级。
|
|
320
|
-
|
|
321
|
-
`entry.tsx` 的 hooks 仍然保留,适合补充上下文和业务语义:
|
|
322
|
-
|
|
323
|
-
```ts
|
|
324
|
-
// src/entry.tsx
|
|
325
|
-
export default {
|
|
326
|
-
devInspector: true,
|
|
327
|
-
beforeStart({ telemetry }) {
|
|
328
|
-
telemetry.setUser(readPublicUser());
|
|
329
|
-
telemetry.track('app.client_ready', { source: 'entry' });
|
|
330
|
-
},
|
|
331
|
-
onNavigate(url, { telemetry }) {
|
|
332
|
-
telemetry.track('navigation.section_enter', { path: url.pathname });
|
|
333
|
-
},
|
|
334
|
-
onActionError(error, actionId, { telemetry }) {
|
|
335
|
-
// engine 已自动错误上报;这里只补一条产品漏斗事件。
|
|
336
|
-
telemetry.track('server_action.failure_seen', {
|
|
337
|
-
actionId,
|
|
338
|
-
message: error instanceof Error ? error.message : String(error),
|
|
339
|
-
});
|
|
91
|
+
routes: ['/about'], concurrent: 3,
|
|
92
|
+
requestTimeoutMs: 30_000, maxRetries: 3,
|
|
93
|
+
retryBaseDelayMs: 200, failBuildThreshold: 0.05,
|
|
340
94
|
},
|
|
341
|
-
};
|
|
342
|
-
```
|
|
343
|
-
|
|
344
|
-
完整的「getting started」(含 i18n / SEO / Server Actions)请看 **[docs/getting-started.md](./docs/getting-started.md)**。
|
|
345
|
-
|
|
346
|
-
## 核心卖点
|
|
347
|
-
|
|
348
|
-
```
|
|
349
|
-
┌──────────────────────────────────────────────────────┐
|
|
350
|
-
│ 用户写的代码(业务) │
|
|
351
|
-
│ src/routes.tsx ← 唯一路由源 │
|
|
352
|
-
│ src/app.tsx ← App shell + routes 调用 │
|
|
353
|
-
│ src/pages/, components/ ← 业务组件 │
|
|
354
|
-
│ src/actions/ ← Server Actions │
|
|
355
|
-
│ src/entry.server.tsx ← (可选) 请求期 hooks │
|
|
356
|
-
│ ssr.config.ts ← (可选) 路由级渲染模式 │
|
|
357
|
-
└──────────────────────┬───────────────────────────────┘
|
|
358
|
-
│
|
|
359
|
-
┌──────────────────────▼───────────────────────────────┐
|
|
360
|
-
│ Engine(默认提供,零配置) │
|
|
361
|
-
│ • RSC fetch handler(@vitejs/plugin-rsc) │
|
|
362
|
-
│ • SSR HTML 转换(react-dom/server.edge) │
|
|
363
|
-
│ • 浏览器水合 / 客户端导航 / Server Action 调用 │
|
|
364
|
-
│ • ISR 缓存(LRU + SWR + 标签失效) │
|
|
365
|
-
│ • SSG spider(构建期预生成) │
|
|
366
|
-
│ • SEO sitemap / robots / OG image │
|
|
367
|
-
│ • page-level SEO + API SEO 下发 │
|
|
368
|
-
│ • i18n URL 路由 + 字典缓存 + getI18n() │
|
|
369
|
-
│ • A/B testing │
|
|
370
|
-
│ • csr-shell fallback(server 崩溃自救) │
|
|
371
|
-
│ • dev render inspector(开发态渲染模式浮层) │
|
|
372
|
-
│ • browser analytics / error-reporting 生命周期桥接 │
|
|
373
|
-
│ • Sentry / Datadog / OTel adapter(一行接入) │
|
|
374
|
-
│ • Image / Font 优化插件(next-style) │
|
|
375
|
-
└──────────────────────────────────────────────────────┘
|
|
376
|
-
```
|
|
377
|
-
|
|
378
|
-
**真正甩开 Next.js 的优势**:
|
|
379
|
-
- Vite 8 dev HMR(不是 Webpack/Turbopack)
|
|
380
|
-
- 单 Express 进程,可 hack 中间件链
|
|
381
|
-
- SEO 在 page export + runtime.seo 下发层分层收口,不散落到组件渲染树
|
|
382
|
-
- L1+L2 hybrid cache(进程内 LRU + 可选 Redis 写穿)
|
|
383
|
-
- A/B 变体内建
|
|
384
|
-
- 显式 `RenderModeType = 'ssg' | 'isr' | 'ssr'`,不靠隐式 segment config
|
|
385
|
-
|
|
386
|
-
## 性能 benchmark
|
|
387
|
-
|
|
388
|
-
baseline:[`bench/baseline.json`](./bench/baseline.json) —— 由 [`bench/app/`](./bench/app/)
|
|
389
|
-
(self-contained 最小 ISR 应用)跑出。bench 结果会写入 `bench_protocol` 与
|
|
390
|
-
`runner_id`,只有协议、并发档、时长、Node major 和 runner class 一致时才做
|
|
391
|
-
raw QPS/P95 退化比较;否则只做当前结果健康检查并提示重新播种 baseline。
|
|
392
|
-
|
|
393
|
-
当前基线协议:Node 22 · 单进程 · 3s warmup · 8s/tier · 2s cooldown ·
|
|
394
|
-
tiers 10/100/1000。
|
|
395
|
-
|
|
396
|
-
复现:`cd bench/app && pnpm run build && pnpm start`,
|
|
397
|
-
另一终端跑 `BENCH_TIERS=10,100,1000 BENCH_DURATION=8 pnpm bench`。bench 退化
|
|
398
|
-
追踪走 [`.github/workflows/bench.yml`](./.github/workflows/bench.yml)。GitHub hosted
|
|
399
|
-
runner 跨次硬件不一致时必须重新播种同一 runner class 的 baseline,不能把本地
|
|
400
|
-
Mac/PC 结果直接拿去 gate CI。详细:[docs/performance.md](./docs/performance.md)。
|
|
401
|
-
|
|
402
|
-
## 文档
|
|
403
|
-
|
|
404
|
-
按主题查:
|
|
405
|
-
|
|
406
|
-
| 主题 | 文档 |
|
|
407
|
-
|---|---|
|
|
408
|
-
| 从零搭一个站 | [getting-started.md](./docs/getting-started.md) |
|
|
409
|
-
| 渲染模式(ISR / SSR / SSG / csr-shell) | [render-modes.md](./docs/render-modes.md) |
|
|
410
|
-
| 开发态渲染检查器(Novel ISR Inspector) | [dev-inspector.md](./docs/dev-inspector.md) |
|
|
411
|
-
| 缓存与失效(cacheTag / revalidate / Redis 双层) | [caching.md](./docs/caching.md) |
|
|
412
|
-
| SiteHooks 配置(beforeRequest / i18n / SEO / A/B) | [site-hooks.md](./docs/site-hooks.md) |
|
|
413
|
-
| i18n URL 路由 + 语言协商 | [i18n.md](./docs/i18n.md) |
|
|
414
|
-
| 可观测性(Sentry / Datadog / OTel / Prometheus) | [observability.md](./docs/observability.md) |
|
|
415
|
-
| 生产部署(环境变量 / Docker / Edge runtime / Middleware) | [deployment.md](./docs/deployment.md) |
|
|
416
|
-
| 验证 RSC 是否真的隐藏 server 代码 | [rsc-testing.md](./docs/rsc-testing.md) |
|
|
417
|
-
| 排错与常见坑 | [troubleshooting.md](./docs/troubleshooting.md) |
|
|
418
|
-
| SSR/SPA 失效降级链路 | [deployment/ssr-spa-failover.md](./docs/deployment/ssr-spa-failover.md) |
|
|
419
|
-
|
|
420
|
-
## 渲染模式(一句话)
|
|
421
|
-
|
|
422
|
-
| 模式 | 行为 | 用户级可选 |
|
|
423
|
-
|---|---|---|
|
|
424
|
-
| **isr** | 显式 TTL,过期 SWR 回放 + 后台重渲。命中即入缓存。 | ✅ |
|
|
425
|
-
| **ssr** | 永不入缓存,每次跑完整 RSC + SSR 管线。 | ✅ |
|
|
426
|
-
| **ssg** | 构建期 spider 预生成磁盘 HTML,运行期 TTL × 24。 | ✅ |
|
|
427
|
-
| `csr-shell` | server 崩溃时返回壳 HTML,浏览器自救拉 `_.rsc`。 | ❌(自动兜底) |
|
|
428
|
-
|
|
429
|
-
```
|
|
430
|
-
FallbackChain(自动降级):
|
|
431
|
-
isr → cached → regenerate → server → csr-shell
|
|
432
|
-
ssg → static → regenerate → server → csr-shell
|
|
433
|
-
ssr → server → csr-shell
|
|
434
|
-
```
|
|
435
|
-
|
|
436
|
-
详情:[docs/render-modes.md](./docs/render-modes.md)。
|
|
437
|
-
|
|
438
|
-
## 开发态渲染检查器
|
|
439
|
-
|
|
440
|
-
`pnpm dev` 时,engine 默认 client runtime 会自动注入右下角 **Novel ISR Inspector**。
|
|
441
|
-
它属于 engine,不属于业务 UI:
|
|
442
|
-
|
|
443
|
-
- 通过响应头读取 `x-resolved-mode`、`x-render-strategy`、`x-cache-status`、`x-fallback-used`、`content-language`、`x-i18n-source`
|
|
444
|
-
- 可以在当前 URL 上切换 `?mode=isr|ssr|ssg`,或强制 `?__csr-shell=1` 验证 CSR fallback
|
|
445
|
-
- Shadow DOM 隔离样式,不污染业务 CSS
|
|
446
|
-
- 仅 dev 显示,生产不显示
|
|
447
|
-
|
|
448
|
-
如果业务要关闭它,放到 **client entry**:
|
|
449
|
-
|
|
450
|
-
```ts
|
|
451
|
-
// src/entry.tsx
|
|
452
|
-
export default {
|
|
453
|
-
devInspector: false,
|
|
454
|
-
};
|
|
455
|
-
```
|
|
456
|
-
|
|
457
|
-
不要放到 `src/entry.server.tsx`。`entry.server.tsx` 是 server hooks,不能把 server-only
|
|
458
|
-
配置直接透给浏览器;需要跨端公共配置时应该走 `ssr.config.ts` 或 engine 注入的 client-safe
|
|
459
|
-
public config。详见 [docs/dev-inspector.md](./docs/dev-inspector.md)。
|
|
460
|
-
|
|
461
|
-
## Routes / SEO / i18n 标准写法
|
|
462
|
-
|
|
463
|
-
### Routes:业务只写一个源
|
|
464
|
-
|
|
465
|
-
`defineRoutes({ routes, notFound })` 是业务唯一需要维护的路由声明。不要在业务项目里再拆 `routes.ssr`、`routes.spa`、`spaModules`、`ssrModules` 或手写 loader 分支。第一性原理很简单:一条路由只应该对应一棵 RSC tree,ISR / SSR / SSG / CSR recovery 的执行策略是 engine 的职责。
|
|
466
|
-
|
|
467
|
-
```tsx
|
|
468
|
-
import { defineRoutes } from '@novel-isr/engine/runtime';
|
|
469
|
-
|
|
470
|
-
export const { routes } = defineRoutes({
|
|
471
|
-
notFound: { load: () => import('./pages/NotFoundPage') },
|
|
472
|
-
routes: [{ path: '/', load: () => import('./pages/HomePage') }],
|
|
473
95
|
});
|
|
474
96
|
```
|
|
475
97
|
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
页面模块可以导出静态 `seo` 或动态 `seo(ctx)` / `generateSeo(ctx)`。Engine 会在 server entry 里先加载 i18n,再解析 page SEO,因此页面 SEO 里可以直接调用 `getI18n()`。
|
|
479
|
-
|
|
480
|
-
```tsx
|
|
481
|
-
// src/pages/BookDetailPage.tsx
|
|
482
|
-
import { getI18n } from '@novel-isr/engine/runtime';
|
|
483
|
-
|
|
484
|
-
export async function seo({ params }: { params: { id: string } }) {
|
|
485
|
-
const book = await fetchBook(params.id);
|
|
486
|
-
return {
|
|
487
|
-
title: getI18n('seo.book.title', { title: book.title }),
|
|
488
|
-
description: book.summary,
|
|
489
|
-
ogType: 'book',
|
|
490
|
-
image: book.cover,
|
|
491
|
-
};
|
|
492
|
-
}
|
|
493
|
-
|
|
494
|
-
export default async function BookDetailPage() {
|
|
495
|
-
// ...
|
|
496
|
-
}
|
|
497
|
-
```
|
|
498
|
-
|
|
499
|
-
`runtime.seo` 用来接 API / CMS 下发的 SEO:`endpoint`、`ttl`、`fallbackLocal`
|
|
500
|
-
都放在 `ssr.config.ts`。`entry.server.tsx` 不承载 SEO 数据源配置,只负责本次请求的
|
|
501
|
-
用户、租户、分层和错误上报。
|
|
502
|
-
|
|
503
|
-
合并顺序:`page seo` 提供页面默认值,`SiteHooks seo` 提供远端覆盖值;最终 `<title>`、`meta`、canonical、Open Graph、JSON-LD 都由 engine 注入到 SSR HTML 的 `<head>`,业务组件里不需要手写 `<title>` / `<meta>`。
|
|
504
|
-
|
|
505
|
-
### i18n:服务端拉取一次,RSC payload 复用
|
|
506
|
-
|
|
507
|
-
商业项目推荐由 API 下发字典。`runtime.i18n` 统一声明 `locales`、`defaultLocale`、
|
|
508
|
-
`endpoint`、`ttl`、`fallbackLocal`;engine 会生成请求期 loader,页面不需要写 Provider。
|
|
509
|
-
|
|
510
|
-
业务侧统一用 `getI18n(key, params?, fallback?)`,不需要手写 Provider。
|
|
511
|
-
|
|
512
|
-
```tsx
|
|
513
|
-
import { getI18n } from '@novel-isr/engine/runtime';
|
|
514
|
-
|
|
515
|
-
getI18n('home.hero.title');
|
|
516
|
-
getI18n('book.count', { count: 12 }); // 字典里写 "共 {count} 本书"
|
|
517
|
-
```
|
|
518
|
-
|
|
519
|
-
变量占位符是 `{name}`,不是 `$name`。例如:
|
|
98
|
+
`package.json` 脚本:
|
|
520
99
|
|
|
521
100
|
```json
|
|
522
101
|
{
|
|
523
|
-
"
|
|
524
|
-
"
|
|
525
|
-
"
|
|
102
|
+
"scripts": {
|
|
103
|
+
"dev": "isr-engine dev",
|
|
104
|
+
"build": "vite build",
|
|
105
|
+
"start": "isr-engine start"
|
|
526
106
|
}
|
|
527
107
|
}
|
|
528
108
|
```
|
|
529
109
|
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
### Rate limiting / 服务端 trace:不在 engine 范畴
|
|
535
|
-
|
|
536
|
-
业界共识(Next.js / Remix / Astro / SvelteKit):渲染框架不做 rate limiting 和服务端 trace。
|
|
537
|
-
- **Rate limit** 在 CDN / WAF / API Gateway 层做:Cloudflare WAF / AWS WAF / Vercel Edge / Kong / Envoy
|
|
538
|
-
- **Trace + 错误** 走 OpenTelemetry → Honeycomb / Datadog / Sentry
|
|
539
|
-
- **业务事件埋点** 仍在 `runtime.telemetry.events`(engine 提供,跟 client 自动接入)
|
|
540
|
-
|
|
541
|
-
应用层兜底 rate-limit 真有需要的话用独立 middleware(`express-rate-limit` 等),不要进框架。
|
|
542
|
-
|
|
543
|
-
### server.strictPort:端口严格模式
|
|
544
|
-
|
|
545
|
-
`server.strictPort` 是业务可见配置:
|
|
546
|
-
|
|
547
|
-
```ts
|
|
548
|
-
server: {
|
|
549
|
-
port: Number(process.env.PORT ?? 3000),
|
|
550
|
-
host: process.env.HOST,
|
|
551
|
-
strictPort: process.env.NODE_ENV !== 'development',
|
|
552
|
-
ops: {
|
|
553
|
-
authToken: process.env.ISR_OPS_TOKEN,
|
|
554
|
-
tokenHeader: 'x-isr-admin-token',
|
|
555
|
-
health: { enabled: true, public: true },
|
|
556
|
-
metrics: { enabled: process.env.ENABLE_METRICS === '1', public: false },
|
|
557
|
-
},
|
|
558
|
-
}
|
|
110
|
+
```bash
|
|
111
|
+
npm run dev # 默认 http://localhost:3000
|
|
112
|
+
npm run build # 构建 RSC/SSR/client,并预渲染 SSG 路由
|
|
113
|
+
NODE_ENV=production npm run start # 从应用根目录启动生产服务
|
|
559
114
|
```
|
|
560
115
|
|
|
561
|
-
- `
|
|
562
|
-
- `false`:端口被占用时最多尝试后续 20 个端口,适合本地开发。
|
|
563
|
-
- `server.strictPort` 是公开配置的一部分;生产项目应显式写出,方便审查部署行为。
|
|
564
|
-
|
|
565
|
-
## 与业界方案对比
|
|
566
|
-
|
|
567
|
-
| 能力 | Next.js App Router | Waku | RedwoodJS | **isr-engine** |
|
|
568
|
-
|---|---|---|---|---|
|
|
569
|
-
| RSC 双 entry 模型 | ✅ 自实现 | ✅ plugin-rsc | ✅ 自实现 | ✅ plugin-rsc |
|
|
570
|
-
| ISR 缓存层 | ✅ | ❌ | ⚠️ | ✅ |
|
|
571
|
-
| `revalidatePath` / `revalidateTag` | ✅ | ⚠️ 实验 | ❌ | ✅ |
|
|
572
|
-
| `cacheTag` 精准失效 | ✅ | ❌ | ❌ | ✅ |
|
|
573
|
-
| 路由级 mode 配置 | ⚠️ segment config | ❌ | ❌ | ✅ ssr.config.ts |
|
|
574
|
-
| zero-config 入口 | ⚠️ 必须用 app/ 文件夹 | ✅ | ⚠️ | ✅ routes + app.tsx |
|
|
575
|
-
| csr-shell server 崩溃兜底 | ❌ | ❌ | ❌ | ✅ |
|
|
576
|
-
| 构建栈灵活度 | ❌ 绑死自家栈 | ✅ Vite | ❌ 绑死自家栈 | ✅ Vite |
|
|
577
|
-
| 内置图片 / 字体优化 | ✅ | ❌ | ⚠️ | ✅ |
|
|
578
|
-
| Edge runtime 支持 | ✅ | ⚠️ | ❌ | ✅(CF / Vercel adapter;Deno / Bun 走原生 `{fetch}`) |
|
|
579
|
-
| 单元测试覆盖 | 数千用例 | ⚠️ | ✅ | 60 文件 / 728 tests / ~61% |
|
|
580
|
-
|
|
581
|
-
定位:**中等规模业务的 ISR / SSG / Fallback 编排层**,构建于 React 19 + `@vitejs/plugin-rsc` 官方流水线之上。
|
|
582
|
-
|
|
583
|
-
## 生产可用性诚实评估
|
|
584
|
-
|
|
585
|
-
**当前阶段:alpha** —— 单一首发项目(novel-rating)在自用,外部用户尚未 burn-in。
|
|
586
|
-
v2.1 做了 Security & Reliability 硬化,v2.2 加了 ISR 缓存层 single-flight /
|
|
587
|
-
OOM 防御 / 命名空间失效 / 边缘预热 / CPU-aware 并发 5 项工业级优化,
|
|
588
|
-
v2.3.1 收口了消费侧首跑 0 配置 + express 5 + 入口架构清理,
|
|
589
|
-
v2.5 系列补上 ISR 缓存可观测性(`X-Cache-Stale-Reason` / inventory 端点)、500 兜底页
|
|
590
|
-
和 telemetry 上传退避。但**离 1.0 stable 还差**:
|
|
591
|
-
|
|
592
|
-
✅ **稳的部分**:
|
|
593
|
-
- Flight 协议委托给官方 `@vitejs/plugin-rsc@^0.5.26`,不自维护
|
|
594
|
-
- 依赖全是工业级(Express 5 / Helmet / Prometheus / sitemap / lru-cache / ioredis)
|
|
595
|
-
- 728 tests / ~61% 行覆盖;CI 任何分支 push 都跑 lint+typecheck+test
|
|
596
|
-
- bench 退化追踪走 nightly `bench.yml`(信息性输出,不 gate release)
|
|
597
|
-
- GitHub Packages 发布有 3 段 gate(lint+test+build),任一失败 → 不发布
|
|
598
|
-
- 安全硬化覆盖了 Set-Cookie 跨用户回放、SSG 路径穿越、Redis Buffer 破损、
|
|
599
|
-
Pub/Sub 消息丢失等 10 项审计发现项
|
|
600
|
-
- 消费侧首跑 0 配置:v2.3.1 后 `vite.config.ts` 三件套真的能跑起来(详见 CHANGELOG)
|
|
601
|
-
|
|
602
|
-
⚠️ **真上生产你必须知道**:
|
|
603
|
-
- **只有首发项目在用**,未在第二个独立项目里完整 burn-in 过;社区 review 才刚开始
|
|
604
|
-
- 浏览器侧没有持续跑的 e2e(728 测试主要是 Node 侧单测),靠人工
|
|
605
|
-
smoke test。任何 React 19 / plugin-rsc / Vite 升级都需要先在 bench app 里手验
|
|
606
|
-
- Origin 协议只支持 `http1.1` / `https`;HTTP/2 / HTTP/3 应在 CDN / Nginx / Caddy / ALB 终结
|
|
607
|
-
- bench baseline 跨 GitHub hosted runner 硬件不一致(同 SHA 跑两次能飘 ±60% QPS),
|
|
608
|
-
release 不 gate bench;要做 release-blocking bench gate 需自部 self-hosted runner 锁硬件
|
|
609
|
-
- API 在 v1.0 之前可能有破坏性变更,主要风险面:路由 `defineRoutes` 形态、
|
|
610
|
-
`SiteHooks` 配置 schema、ISR cacheTag/revalidate API。会在 CHANGELOG 中
|
|
611
|
-
明确标注 `BREAKING`,但**没有 codemod**。
|
|
612
|
-
|
|
613
|
-
完整改动列表:[CHANGELOG.md](./CHANGELOG.md)。
|
|
614
|
-
|
|
615
|
-
## 开发
|
|
116
|
+
`dev`、`start` 接受 `--port <port>` 和 `--host <host>`,显式参数覆盖配置。`dev --no-open` 关闭自动打开浏览器。构建和启动生产进程时通过运行环境设置 `NODE_ENV`,避免 `.env*` 中的 `NODE_ENV=development` 影响生产构建。
|
|
616
117
|
|
|
617
|
-
|
|
618
|
-
pnpm install
|
|
619
|
-
pnpm test # vitest run
|
|
620
|
-
pnpm lint # eslint(含 prettier check via eslint-plugin-prettier)
|
|
621
|
-
pnpm type-check # tsc --noEmit
|
|
622
|
-
pnpm bench # autocannon load test(不阻塞)
|
|
623
|
-
pnpm check # type-check + lint + test
|
|
624
|
-
pnpm build # vite build → dist/
|
|
625
|
-
```
|
|
118
|
+
## 渲染与生产缓存
|
|
626
119
|
|
|
627
|
-
|
|
120
|
+
| 模式 | 行为 |
|
|
121
|
+
| --- | --- |
|
|
122
|
+
| `isr` | 按 TTL 缓存;SWR 窗口内返回旧响应并后台重渲,窗口结束后重新生成。 |
|
|
123
|
+
| `ssg` | 构建时预生成配置的路由;运行时仍受缓存新鲜度与失效策略管理。 |
|
|
124
|
+
| `ssr` | 每次请求渲染,跳过共享页面缓存。 |
|
|
628
125
|
|
|
629
|
-
|
|
630
|
-
npm Enterprise / GitHub Packages)。**任何项目**都可以作为消费方接它,通过语义
|
|
631
|
-
化版本号引用,**不**用 `file:../isr-engine` 这种 sibling 相对路径——sibling 假设
|
|
632
|
-
让两个 repo 互相强耦合,CI checkout 也跑不通。
|
|
126
|
+
TTL 与 SWR 单位为秒。`routes` 控制渲染策略;页面路由可使用 `isr-engine/runtime` 的 `defineRoutes` 统一声明。渲染异常的 `csr-shell` 是自动恢复策略;origin 进程不可用时的切换需在反向代理/CDN 配置。
|
|
633
127
|
|
|
634
|
-
|
|
128
|
+
- 未配置 `runtime.redis.url/host` 时使用进程内存缓存,重启即清空,各实例独立。
|
|
129
|
+
- 显式配置 Redis 后启用远端版本校验和跨实例失效广播,需保留可选依赖 `ioredis`;Redis 连接只读取配置,须如示例显式接入环境变量。多实例共享相同应用的前缀与频道,不同应用/环境使用独立命名空间。
|
|
130
|
+
- 登录态、权限相关或个性化页面应配置为 `ssr`,并在业务层验证身份。请求 hooks 与缓存标签不提供访问控制,也不会自动按用户隔离页面。
|
|
131
|
+
- 授权头、普通业务 Cookie,以及 `private`/`no-store` 等响应会触发缓存保护;不要依赖这些保护代替路由策略。`anon` 与实验 Cookie 有专门的共享缓存规则。
|
|
132
|
+
- Server Component 使用 `cacheTag('site-content')` 声明依赖;数据更新成功后,在受业务鉴权保护的服务端代码中 `await revalidateTag('site-content')` 或 `await revalidatePath('/about')`,从 `isr-engine/rsc` 导入。
|
|
635
133
|
|
|
636
|
-
|
|
637
|
-
# 1. 配 .npmrc(一次性)
|
|
638
|
-
@novel-isr:registry=https://npm.your-company.com/
|
|
639
|
-
//npm.your-company.com/:_authToken=${NPM_TOKEN}
|
|
134
|
+
请求期扩展可放在可选的 `src/entry.server.tsx`,默认导出 `defineAdminSiteHooks({ beforeRequest, onError })`(从 `isr-engine/site-hooks` 导入)。部署配置留在 `ssr.config.ts`;Server Component 用 `getRequestContext()` 读取 hooks 注入的上下文。
|
|
640
135
|
|
|
641
|
-
|
|
642
|
-
{ "dependencies": { "@novel-isr/engine": "^2.6.2" } }
|
|
136
|
+
## 运维与部署
|
|
643
137
|
|
|
644
|
-
|
|
645
|
-
pnpm install
|
|
646
|
-
```
|
|
138
|
+
部署保留完整 `dist/`、应用依赖及 `ssr.config.*`;配置编译需要应用根目录可写的 `.isr-cache/`。容器按需设置 `HOST=0.0.0.0`,反向代理后显式配置 `server.trustProxy` 的可信来源。
|
|
647
139
|
|
|
648
|
-
|
|
140
|
+
`/health` 默认公开。生产 `/metrics` 默认关闭;非公开 metrics/inventory 未配置 `server.ops.authToken` 会自动关闭。启用后通过 `Authorization: Bearer <token>` 或配置的 token header 访问;设为 `public: true` 会绕过 token 校验。
|
|
649
141
|
|
|
650
142
|
```bash
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
# 任何消费项目端
|
|
655
|
-
cd <YOUR_CONSUMER_PROJECT> && pnpm link --global @novel-isr/engine
|
|
656
|
-
# 改完取消 link
|
|
657
|
-
pnpm unlink --global @novel-isr/engine && pnpm install
|
|
143
|
+
curl -fsS http://localhost:3000/health
|
|
144
|
+
curl -fsS -H "x-isr-admin-token: $ISR_OPS_TOKEN" \
|
|
145
|
+
http://localhost:3000/__isr/cache/inventory
|
|
658
146
|
```
|
|
659
147
|
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
仓库里 3 个 workflow 各司其职:
|
|
663
|
-
|
|
664
|
-
| Workflow | 触发 | 跑什么 | 失败后果 |
|
|
665
|
-
|---|---|---|---|
|
|
666
|
-
| **`ci.yml`** | 任何分支 push + PR 到 main/develop | type-check / lint / test / build | branch 标红,PR 不可 merge |
|
|
667
|
-
| **`bench.yml`** | nightly 02:00 UTC + 手动 + perf-sensitive 路径 PR | 起 bench app + 跑 bench + 对比 `bench/baseline.json` | 信息性 fail(不阻断 release,只用于追踪退化) |
|
|
668
|
-
| **`release.yml`** | `git push v*.*.*` tag | 3 段 gate(type+lint / test / build)→ `pnpm publish --access restricted` 到 GitHub Packages | 任一段失败 → 不发布 |
|
|
669
|
-
|
|
670
|
-
**发布到 GitHub Packages**:
|
|
671
|
-
|
|
672
|
-
1. 一次性配置:repo `Settings → Actions → General → Workflow permissions` 切到 **Read and write permissions**(让 `GITHUB_TOKEN` 拿到 `write:packages`)。无需手动配 secret。
|
|
673
|
-
2. 本地:
|
|
674
|
-
```bash
|
|
675
|
-
# 改 package.json version 到 X.Y.Z
|
|
676
|
-
git tag vX.Y.Z
|
|
677
|
-
git push --tags
|
|
678
|
-
```
|
|
679
|
-
3. GitHub Actions 自动跑 release.yml;任一 gate 失败 → 不发布。
|
|
148
|
+
排查页面时先看 `X-Cache-Status`、`X-Resolved-Mode`、`X-Render-Strategy`。本地代理验证可用 `isr-engine test-fallback-local --help`;生产切换由部署层完成,浏览器恢复仍依赖可用的资源与数据服务。
|
|
680
149
|
|
|
681
|
-
|
|
150
|
+
## 公共入口
|
|
682
151
|
|
|
683
|
-
|
|
152
|
+
| 导入路径 | 用途 |
|
|
153
|
+
| --- | --- |
|
|
154
|
+
| `isr-engine` | Vite 插件、Node 编排 API 与公共类型。 |
|
|
155
|
+
| `isr-engine/config` | `defineIsrConfig`、`defineRuntimeConfig`。 |
|
|
156
|
+
| `isr-engine/rsc` | 缓存标签、失效、服务端请求上下文。 |
|
|
157
|
+
| `isr-engine/runtime` | 页面路由、边界、i18n 与浏览器 telemetry。 |
|
|
158
|
+
| `isr-engine/site-hooks` | 请求 hooks 工厂与 Cookie 工具。 |
|
|
159
|
+
| `isr-engine/server-entry`、`isr-engine/client-entry` | 高级入口工厂;由 Vite 转译其源码。 |
|
|
160
|
+
| `isr-engine/image` | 图片组件。 |
|
|
161
|
+
| `isr-engine/auto-observability`、`isr-engine/adapters/observability` | 自动观测与观测适配器。 |
|
|
162
|
+
| `isr-engine/adapters/runtime` | Fetch handler 的平台适配器。 |
|
|
163
|
+
| `isr-engine/package.json` | 包元数据。 |
|
|
684
164
|
|
|
685
|
-
##
|
|
165
|
+
## 文档与发布
|
|
686
166
|
|
|
687
|
-
|
|
688
|
-
2. **第一性原理** —— 不造假概念(csr 不是用户级 mode,是 fallback 兜底)
|
|
689
|
-
3. **横切能力 engine 默认提供** —— trace-id / render-ms / SEO / 安全头自动
|
|
690
|
-
4. **业务扩展用 FaaS hooks** —— 不强制学协议代码
|
|
691
|
-
5. **不手写 Flight** —— 完全依赖 [@vitejs/plugin-rsc](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-rsc),与 React 19 / Vite 8 升级路径对齐
|
|
167
|
+
配置字段与默认行为见 [公共配置类型](./src/types/ISRConfig.ts) 和 [默认配置](./src/config/defaults.ts)。
|
|
692
168
|
|
|
693
|
-
|
|
169
|
+
`main` 的自动发布流程通过验证后由 semantic-release 计算版本,以 npm OIDC 发布到 `registry.npmjs.org`;配置见 [发布工作流](./.github/workflows/publish.yml) 与 [release.config.mjs](./release.config.mjs)。npm 端需绑定对应仓库和工作流的 Trusted Publisher。
|
|
694
170
|
|
|
695
|
-
|
|
171
|
+
许可证声明为 **UNLICENSED**,以 `package.json` 为准。
|