Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.
TypeScript albumsexif-extractiongeocodinglive-photomotion-photophoto-galleryphoto-sharingwebgl-viewer
fix: allow processor registration routes and report safe connection diagnostics
Timothy Yinf7ae75423632
diff --git a/apps/cloud/server/middleware/platform-boundary.ts b/apps/cloud/server/middleware/platform-boundary.tsindex 9756b612..06b7dda4 100644--- a/apps/cloud/server/middleware/platform-boundary.ts+++ b/apps/cloud/server/middleware/platform-boundary.ts@@ -1,3 +1,4 @@+import { isProcessorAction } from '@chronoframe/contracts/processor'import { accountRouteAllowed } from '../utils/account-routes'/** Enable explicit platform endpoints only; never fall back to Self-hosted APIs. */export default defineEventHandler((event) => {@@ -32,11 +33,10 @@ export default defineEventHandler((event) => {/^\/api\/sites\/[1-9][0-9]*\/(?:context|events|settings|domains|map)$/.test(path,)+ const processorAction = /^\/api\/internal\/worker\/([a-z-]+)$/.exec(path)?.[1]if (/^\/api\/sites\/[1-9][0-9]*\/media(?:\/|$)/.test(path) ||- /^\/api\/internal\/worker\/(?:claim|heartbeat|grant|complete|fail|cleanup)$/.test(- path,- )+ isProcessorAction(processorAction))returnif (platformRoute || accountRouteAllowed(path, event.method)) returndiff --git a/apps/worker/README.md b/apps/worker/README.mdindex 7e46f0ec..db66fc4e 100644--- a/apps/worker/README.md+++ b/apps/worker/README.md@@ -144,3 +144,21 @@ CHRONOFRAME_WORKER_ENV_FILE=/opt/chronoframe/processor/processor.env \这里的 `CHRONOFRAME_WORKER_ENV_FILE` 是现有 Compose 文件用于选择环境文件的变量名;文件内仍使用新的 `CHRONOFRAME_PROCESSOR_KEY`。源码 Compose 示例启用了只读根文件系统和 `/tmp` 临时内存盘,并配置了内存、CPU、进程数等限制。处理照片时需要临时文件空间,请按服务器资源及管理端阈值调整这些限制。++## 连接排查++查看容器日志:++```bash+docker compose logs --tail=100 processor+```++首次连接成功会输出 `processor.connected`。连接重试日志包含 `action`、`code`、`hint`,收到 HTTP 响应时还包含 `httpStatus` 和可用的 `cfRay`,便于与 Cloud 日志关联;不会输出连接密钥或远端响应正文。++- `503` / `portal_unavailable`:检查 Cloud 服务、部署版本及处理端路由是否正常。+- `401`:检查节点是否启用,以及连接密钥是否已轮换或配置错误。+- `400`:检查 Cloud 与处理端的协议版本是否匹配。+- `403` 或重定向:检查 Cloudflare Access、门户地址及访问策略。+- `container_dns_failure`、`container_network_unreachable` 或 `container_tls_verification_failed`:检查容器内的 DNS、网络或证书配置。宿主机能 ping 通并不代表容器可以通过 HTTPS 连接。++排查时可以提供上述诊断字段和镜像版本,不要发送连接密钥或完整环境文件。diff --git a/apps/worker/src/diagnostics.ts b/apps/worker/src/diagnostics.tsnew file mode 100644index 00000000..08a854e2--- /dev/null+++ b/apps/worker/src/diagnostics.ts@@ -0,0 +1,123 @@+import type { ProcessorAction } from '@chronoframe/contracts/processor'+export type ProcessorConnectionCode =+ | 'portal_request_failed'+ | 'portal_redirect'+ | 'portal_response_invalid'+ | 'portal_transport_failed'+ | 'portal_configuration_invalid'+const networkCodes = new Set([+ 'ENETUNREACH',+ 'EHOSTUNREACH',+ 'ENETDOWN',+ 'ENOTFOUND',+ 'EAI_AGAIN',+ 'ECONNREFUSED',+ 'ECONNRESET',+ 'ETIMEDOUT',+ 'CERT_HAS_EXPIRED',+ 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',+ 'SELF_SIGNED_CERT_IN_CHAIN',+ 'DEPTH_ZERO_SELF_SIGNED_CERT',+ 'ERR_TLS_CERT_ALTNAME_INVALID',+])+export function connectionNetworkCodes(error: unknown): string[] {+ const result = new Set<string>(),+ seen = new Set<unknown>()+ function visit(value: unknown, depth = 0) {+ if (!value || typeof value !== 'object' || depth > 4 || seen.has(value))+ return+ seen.add(value)+ const item = value as {+ code?: unknown+ name?: unknown+ cause?: unknown+ errors?: unknown+ }+ if (typeof item.code === 'string' && networkCodes.has(item.code))+ result.add(item.code)+ if (item.name === 'TimeoutError') result.add('ETIMEDOUT')+ visit(item.cause, depth + 1)+ if (Array.isArray(item.errors))+ for (const nested of item.errors.slice(0, 8)) visit(nested, depth + 1)+ }+ visit(error)+ return [...result].slice(0, 8)+}+/** Contains only bounded classifications, never remote bodies, URLs, headers or exception messages. */+export class ProcessorConnectionError extends Error {+ readonly code: ProcessorConnectionCode+ readonly action: ProcessorAction+ readonly httpStatus?: number+ readonly cfRay?: string+ readonly networkCodes: string[]+ constructor(+ code: ProcessorConnectionCode,+ action: ProcessorAction,+ httpStatus?: number,+ cfRay?: string,+ networkCodes: string[] = [],+ ) {+ super(code)+ this.code = code+ this.action = action+ this.httpStatus = httpStatus+ this.cfRay = cfRay+ this.networkCodes = networkCodes+ }+ diagnostic() {+ let hint: string+ if (+ this.networkCodes.some((code) =>+ ['ENETUNREACH', 'EHOSTUNREACH', 'ENETDOWN'].includes(code),+ )+ )+ hint = 'container_network_unreachable'+ else if (+ this.networkCodes.some((code) =>+ ['ENOTFOUND', 'EAI_AGAIN'].includes(code),+ )+ )+ hint = 'container_dns_failure'+ else if (+ this.networkCodes.some(+ (code) => code.includes('CERT') || code.includes('VERIFY'),+ )+ )+ hint = 'container_tls_verification_failed'+ else if (this.networkCodes.includes('ETIMEDOUT'))+ hint = 'portal_connection_timeout'+ else if (this.code === 'portal_configuration_invalid')+ hint = 'node_key_or_protocol_configuration_mismatch'+ else if (this.code === 'portal_redirect')+ hint = 'portal_redirect_or_access_login'+ else if (this.httpStatus === 401)+ hint = 'node_key_invalid_revoked_or_disabled'+ else if (this.httpStatus === 403) hint = 'portal_origin_or_access_denied'+ else if (this.httpStatus === 400)+ hint = 'portal_protocol_mismatch_or_invalid_request'+ else if (this.httpStatus === 404 || this.httpStatus === 405)+ hint = 'portal_route_or_version_mismatch'+ else if (this.httpStatus === 429) hint = 'portal_rate_limited'+ else if (this.httpStatus && this.httpStatus >= 500)+ hint = 'portal_unavailable'+ else if (this.code === 'portal_response_invalid')+ hint = 'portal_non_json_response_or_access_login'+ else hint = 'portal_transport_failed'+ return {+ code: this.code,+ action: this.action,+ ...(this.httpStatus ? { httpStatus: this.httpStatus } : {}),+ ...(this.cfRay ? { cfRay: this.cfRay } : {}),+ ...(this.networkCodes.length ? { networkCodes: this.networkCodes } : {}),+ hint,+ }+ }+}+export function processorConnectionDiagnostic(error: unknown) {+ return error instanceof ProcessorConnectionError+ ? error.diagnostic()+ : {+ code: 'processor_connection_error',+ hint: 'inspect_cloud_and_processor_versions',+ }+}diff --git a/apps/worker/src/gateway.ts b/apps/worker/src/gateway.tsindex e85acf2a..5a6b7beb 100644--- a/apps/worker/src/gateway.ts+++ b/apps/worker/src/gateway.ts@@ -1,13 +1,11 @@-type WorkerAction =- | 'register'- | 'status'- | 'geocoding-slot'- | 'claim'- | 'heartbeat'- | 'grant'- | 'complete'- | 'fail'- | 'cleanup'+import {+ isProcessorAction,+ type ProcessorAction as WorkerAction,+} from '@chronoframe/contracts/processor'+import {+ ProcessorConnectionError,+ connectionNetworkCodes,+} from './diagnostics.ts'interface GatewayConfig {origin: stringsecret: string@@ -64,35 +62,57 @@ export function createWorkerGateway(body: unknown,signal?: AbortSignal,): Promise<T> {- if (- ![- 'register',- 'status',- 'geocoding-slot',- 'claim',- 'heartbeat',- 'grant',- 'complete',- 'fail',- 'cleanup',- ].includes(action)- )+ if (!isProcessorAction(action))throw new Error('Invalid worker gateway action')- const response = await transport(- origin + '/api/internal/worker/' + action,- {+ let response: Response+ try {+ response = await transport(origin + '/api/internal/worker/' + action, {method: 'POST',- redirect: 'error',+ redirect: 'manual',headers,body: JSON.stringify(body),signal: signal ?? AbortSignal.timeout(30000),- },- )- if (!response.ok) throw new Error('portal_request_failed')+ })+ } catch (error) {+ throw new ProcessorConnectionError(+ 'portal_transport_failed',+ action,+ undefined,+ undefined,+ connectionNetworkCodes(error),+ )+ }+ const ray = response.headers.get('cf-ray') ?? ''+ const cfRay = /^[a-f0-9]{16,32}(?:-[a-z0-9]{3,10})?$/i.test(ray)+ ? ray+ : undefined+ if (response.status >= 300 && response.status < 400) {+ await response.body?.cancel().catch(() => {})+ throw new ProcessorConnectionError(+ 'portal_redirect',+ action,+ response.status,+ cfRay,+ )+ }+ if (!response.ok) {+ await response.body?.cancel().catch(() => {})+ throw new ProcessorConnectionError(+ 'portal_request_failed',+ action,+ response.status,+ cfRay,+ )+ }try {return (await response.json()) as T} catch {- throw new Error('portal_response_invalid')+ throw new ProcessorConnectionError(+ 'portal_response_invalid',+ action,+ response.status,+ cfRay,+ )}}}diff --git a/apps/worker/src/index.ts b/apps/worker/src/index.tsindex f7721929..3affda4f 100644--- a/apps/worker/src/index.ts+++ b/apps/worker/src/index.ts@@ -1,3 +1,7 @@+import {+ ProcessorConnectionError,+ processorConnectionDiagnostic,+} from './diagnostics.ts'import os from 'node:os'import {type ProcessorConfiguration,@@ -34,12 +38,20 @@ async function reportStatus(register = false) {},},)- configuration = await openProcessorConfiguration(- connectionKey,- result,- nonce,- performance.now() - started,- )+ try {+ configuration = await openProcessorConfiguration(+ connectionKey,+ result,+ nonce,+ performance.now() - started,+ )+ } catch {+ throw new ProcessorConnectionError(+ 'portal_configuration_invalid',+ register ? 'register' : 'status',+ )+ }+ if (register) console.log(JSON.stringify({ event: 'processor.connected' }))lastStatus = performance.now()}const rpc = createWorkerGateway({@@ -189,7 +201,15 @@ while (!stopping) {jobId: work.lease.id,siteId: work.lease.siteId,attemptId: work.lease.attemptId,- code: aborted ? 'lease_or_timeout' : 'processing_error',+ ...(error instanceof ProcessorConnectionError+ ? processorConnectionDiagnostic(error)+ : {+ code: aborted+ ? 'lease_or_timeout'+ : error instanceof WorkerProcessingError+ ? error.message+ : 'processing_error',+ }),}),)} finally {@@ -197,9 +217,14 @@ while (!stopping) {clearTimeout(timeout)}await rpc('cleanup', {}).catch(() => {})- } catch {+ } catch (error) {if (!stopping) {- console.log(JSON.stringify({ event: 'worker.connection_retry' }))+ console.log(+ JSON.stringify({+ event: 'worker.connection_retry',+ ...processorConnectionDiagnostic(error),+ }),+ )await delay(5000, undefined, { signal: shutdown.signal }).catch(() => {})}}diff --git a/packages/contracts/src/processor.ts b/packages/contracts/src/processor.tsindex 8f257f0d..5e425e3f 100644--- a/packages/contracts/src/processor.ts+++ b/packages/contracts/src/processor.ts@@ -1,3 +1,22 @@+/** Shared allowlist for the Cloud boundary and processing-node transport. */+export const PROCESSOR_ACTIONS = [+ 'register',+ 'status',+ 'geocoding-slot',+ 'claim',+ 'heartbeat',+ 'grant',+ 'complete',+ 'fail',+ 'cleanup',+] as const+export type ProcessorAction = (typeof PROCESSOR_ACTIONS)[number]+export function isProcessorAction(value: unknown): value is ProcessorAction {+ return (+ typeof value === 'string' &&+ PROCESSOR_ACTIONS.some((action) => action === value)+ )+}/** Server-owned processing policy; shared by Cloud and Docker processing nodes. */export interface ProcessorLimits {maxFileBytes: numberdiff --git a/tests/processor-connectivity.test.ts b/tests/processor-connectivity.test.tsnew file mode 100644index 00000000..da690a99--- /dev/null+++ b/tests/processor-connectivity.test.ts@@ -0,0 +1,200 @@+import test from 'node:test'+import assert from 'node:assert/strict'+import { readFile } from 'node:fs/promises'+import ts from 'typescript'+import {+ PROCESSOR_ACTIONS,+ isProcessorAction,+} from '../packages/contracts/src/processor.ts'+import { createWorkerGateway } from '../apps/worker/src/gateway.ts'+import {+ ProcessorConnectionError,+ processorConnectionDiagnostic,+} from '../apps/worker/src/diagnostics.ts'++async function compile(file: string, deps: Record<string, unknown>) {+ const source = (await readFile(file, 'utf8')).replace(+ /^import[\s\S]*?from ['"][^'"]+['"]\s*\n/gm,+ '',+ )+ const code = ts.transpileModule(source, {+ compilerOptions: {+ module: ts.ModuleKind.CommonJS,+ target: ts.ScriptTarget.ES2022,+ },+ }).outputText+ return new Function(+ 'exports',+ ...Object.keys(deps),+ code + ';return exports.default',+ )({}, ...Object.values(deps))+}+test('Cloud boundary admits every processing protocol action while rejecting unknown internal routes', async () => {+ const boundary = await compile(+ 'apps/cloud/server/middleware/platform-boundary.ts',+ {+ defineEventHandler: (f: unknown) => f,+ setResponseHeader: () => {},+ getRequestURL: (e: { path: string }) =>+ new URL('https://app.example' + e.path),+ accountRouteAllowed: () => false,+ isProcessorAction,+ createError: (value: { statusCode: number }) =>+ Object.assign(new Error('boundary'), value),+ },+ )+ for (const action of PROCESSOR_ACTIONS)+ await boundary({ path: '/api/internal/worker/' + action, method: 'POST' })+ for (const path of [+ '/api/internal/worker/unknown',+ '/api/internal/worker/register/extra',+ '/api/internal/worker/',+ '/api/internal/other/register',+ ])+ assert.throws(() => boundary({ path, method: 'POST' }), { statusCode: 503 })+})+const secret = 'private-node-secret-'.repeat(3),+ origin = 'https://app.example'+test('HTTP diagnostics expose the action, status and CF ray without reflecting credentials or remote response bodies', async () => {+ for (const status of [400, 401, 403, 404, 429, 500, 503]) {+ const rpc = createWorkerGateway(+ { origin, secret },+ async () =>+ new Response('private-response-' + secret, {+ status,+ headers: { 'cf-ray': 'a53236b7b988c0f4-DFW', 'set-cookie': secret },+ }),+ )+ await assert.rejects(rpc('register', { nonce: 'request' }), (error) => {+ assert(error instanceof ProcessorConnectionError)+ const diagnostic = processorConnectionDiagnostic(error)+ assert.equal(diagnostic.httpStatus, status)+ assert.equal(diagnostic.action, 'register')+ assert.equal(diagnostic.cfRay, 'a53236b7b988c0f4-DFW')+ assert(!JSON.stringify(error).includes(secret))+ assert(!JSON.stringify(diagnostic).includes('private-response'))+ return true+ })+ }+})+test('redirects and HTML Access pages remain diagnosable without forwarding the connection key', async () => {+ let calls = 0+ const redirect = createWorkerGateway(+ { origin, secret },+ async (_input, init) => {+ calls+++ assert.equal(init?.redirect, 'manual')+ return new Response(null, {+ status: 302,+ headers: { location: 'https://login.example/?secret=' + secret },+ })+ },+ )+ await assert.rejects(redirect('register', {}), (error) => {+ assert(error instanceof ProcessorConnectionError)+ assert.equal(error.diagnostic().hint, 'portal_redirect_or_access_login')+ assert.equal(error.httpStatus, 302)+ assert(!JSON.stringify(error).includes(secret))+ return true+ })+ assert.equal(calls, 1)+ const html = createWorkerGateway(+ { origin, secret },+ async () =>+ new Response('<html>' + secret + '</html>', {+ headers: { 'content-type': 'text/html' },+ }),+ )+ await assert.rejects(html('register', {}), (error) => {+ assert(error instanceof ProcessorConnectionError)+ assert.equal(+ error.diagnostic().hint,+ 'portal_non_json_response_or_access_login',+ )+ assert(!JSON.stringify(error).includes(secret))+ return true+ })+})+test('nested container network errors are classified without logging URLs, raw messages or headers', async () => {+ const rpc = createWorkerGateway({ origin, secret }, async () => {+ throw new TypeError('https://private.example/' + secret, {+ cause: new AggregateError([+ Object.assign(new Error(secret), { code: 'ENETUNREACH' }),+ Object.assign(new Error(secret), { code: 'ECONNREFUSED' }),+ ]),+ })+ })+ await assert.rejects(rpc('register', {}), (error) => {+ assert(error instanceof ProcessorConnectionError)+ assert.deepEqual(error.networkCodes, ['ENETUNREACH', 'ECONNREFUSED'])+ assert.equal(error.diagnostic().hint, 'container_network_unreachable')+ assert(!JSON.stringify(error).includes(secret))+ assert(!JSON.stringify(error).includes('private.example'))+ return true+ })+})+test('connection retry logs retain safe diagnostics instead of swallowing gateway failures', async () => {+ const source = (await readFile('apps/worker/src/index.ts', 'utf8')).replace(+ /^import[\s\S]*?from ['"][^'"]+['"]\s*\n/gm,+ '',+ )+ const code = ts.transpileModule(source, {+ compilerOptions: {+ module: ts.ModuleKind.CommonJS,+ target: ts.ScriptTarget.ES2022,+ },+ }).outputText+ const handlers: Record<string, () => void> = {},+ logs: string[] = []+ const deps = {+ exports: {},+ os: {+ hostname: () => '',+ cpus: () => [],+ loadavg: () => [0],+ totalmem: () => 0,+ freemem: () => 0,+ },+ process: {+ env: {+ CHRONOFRAME_PROCESSOR_KEY: secret,+ CHRONOFRAME_PORTAL_ORIGIN: origin,+ },+ on: (signal: string, fn: () => void) => {+ handlers[signal] = fn+ },+ memoryUsage: () => ({ rss: 0 }),+ },+ randomUUID: () => crypto.randomUUID(),+ createWorkerGateway: () => async () => {+ throw new ProcessorConnectionError(+ 'portal_request_failed',+ 'register',+ 503,+ )+ },+ openProcessorConfiguration: () => {+ throw Error('not reached')+ },+ ProcessorConnectionError,+ processorConnectionDiagnostic,+ delay: async () => {},+ console: {+ log: (raw: string) => {+ logs.push(raw)+ handlers.SIGTERM!()+ },+ },+ }+ await new Function(+ ...Object.keys(deps),+ 'return (async()=>{' + code + '})()',+ )(...Object.values(deps))+ assert.equal(logs.length, 1)+ const event = JSON.parse(logs[0]!)+ assert.equal(event.event, 'worker.connection_retry')+ assert.equal(event.action, 'register')+ assert.equal(event.httpStatus, 503)+ assert.equal(event.hint, 'portal_unavailable')+ assert(!logs[0]!.includes(secret))+})diff --git a/tests/processor-nodes.test.ts b/tests/processor-nodes.test.tsindex 173c343d..a6ef4463 100644--- a/tests/processor-nodes.test.ts+++ b/tests/processor-nodes.test.ts@@ -7,6 +7,7 @@ import { readFile, readdir } from 'node:fs/promises'import { splitSqlQuery } from './helpers/sql.ts'import {processorCipher,+ isProcessorAction,type ProcessorConfiguration,processorKeyHash,DEFAULT_PROCESSOR_LIMITS,@@ -147,11 +148,45 @@ test('registered node auth revokes old keys; full schema preserves assets and fetarget: ts.ScriptTarget.ES2022,},}).outputText- const api = new Function(+ const boundarySource = (+ await readFile(+ 'apps/cloud/server/middleware/platform-boundary.ts',+ 'utf8',+ )+ ).replace(/^import[\s\S]*?from ['"][^'"]+['"]\s*\n/gm, '')+ const boundaryCode = ts.transpileModule(boundarySource, {+ compilerOptions: {+ module: ts.ModuleKind.CommonJS,+ target: ts.ScriptTarget.ES2022,+ },+ }).outputText+ const boundaryDeps = {+ exports: {},+ defineEventHandler: (f: unknown) => f,+ setResponseHeader: () => {},+ getRequestURL: (event: { action: string }) =>+ new URL('https://app.example/api/internal/worker/' + event.action),+ accountRouteAllowed: () => false,+ isProcessorAction,+ createError: deps.createError,+ }+ const boundary = new Function(+ ...Object.keys(boundaryDeps),+ boundaryCode + ';return exports.default',+ )(...Object.values(boundaryDeps))+ const handler = new Function('exports',...Object.keys(deps),code + ';return exports.default',)({}, ...Object.values(deps))+ const api = async (event: {+ action: string+ key: string+ body?: unknown+ }) => {+ await boundary(event)+ return handler(event)+ }await assert.rejects(api({ action: 'register', key: 'legacy-shared-key' }),{ statusCode: 401 },diff --git a/tests/processor-review.test.ts b/tests/processor-review.test.tsindex 2a4efd8b..138d6c47 100644--- a/tests/processor-review.test.ts+++ b/tests/processor-review.test.ts@@ -1,3 +1,7 @@+import {+ ProcessorConnectionError,+ processorConnectionDiagnostic,+} from '../apps/worker/src/diagnostics.ts'import test from 'node:test'import assert from 'node:assert/strict'import { readFile } from 'node:fs/promises'@@ -124,6 +128,8 @@ test('a bad post-claim configuration promptly fails the claimed attempt instead}},WorkerProcessingError,+ ProcessorConnectionError,+ processorConnectionDiagnostic,processWork: async () => {processed = true},diff --git a/tests/worker-gateway.test.ts b/tests/worker-gateway.test.tsindex d88c0c94..3af46f5e 100644--- a/tests/worker-gateway.test.ts+++ b/tests/worker-gateway.test.ts@@ -1,5 +1,6 @@import assert from 'node:assert/strict'import test from 'node:test'+import { PROCESSOR_ACTIONS } from '../packages/contracts/src/processor.ts'import { createWorkerGateway } from '../apps/worker/src/gateway.ts'const origin = 'https://staging.portal.example'@@ -20,21 +21,14 @@ test('Worker gateway scopes optional Access credentials to fixed portal actionstransport,)const controller = new AbortController()- for (const action of [- 'claim',- 'heartbeat',- 'grant',- 'complete',- 'fail',- 'cleanup',- ] as const)+ for (const action of PROCESSOR_ACTIONS)assert.deepEqual(await rpc(action, { test: true }, controller.signal), {ok: true,})for (const request of requests) {assert.equal(new URL(request.url).origin, origin)assert.equal(request.method, 'POST')- assert.equal(request.redirect, 'error')+ assert.equal(request.redirect, 'manual')assert.equal(request.headers.get('authorization'), 'Bearer ' + secret)assert.equal(request.headers.get('cf-access-client-id'),@@ -52,7 +46,7 @@ test('Worker gateway scopes optional Access credentials to fixed portal actions)assert.equal(requests.length,- 6,+ PROCESSOR_ACTIONS.length,'an invalid action cannot move credentials to another destination',)const ordinary = createWorkerGateway({ origin, secret }, transport)