diff --git a/package-lock.json b/package-lock.json index 067544e..33bb947 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "telemax", - "version": "1.3.3-beta.5", + "version": "1.3.3-beta.6", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "telemax", - "version": "1.3.3-beta.5", + "version": "1.3.3-beta.6", "license": "AGPL-3.0-only", "dependencies": { "dotenv": "^17.2.3", diff --git a/package.json b/package.json index 99ef6e0..37a833d 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "telemax", "private": true, "license": "AGPL-3.0-only", - "version": "1.3.3-beta.5", + "version": "1.3.3-beta.6", "type": "module", "scripts": { "dev": "tsx watch src/server/app.ts", diff --git a/src/bridge/fileShare.ts b/src/bridge/fileShare.ts index 97dec01..8947721 100644 --- a/src/bridge/fileShare.ts +++ b/src/bridge/fileShare.ts @@ -133,25 +133,31 @@ const HEARTBEAT_STALE_MS = 5 * 60_000; */ const UPLOAD_LOCK_STALE_MS = 12 * 3600_000; /** - * A files-service problem told the way the user asked for (2026-10-11): what happened, a plain «why», - * what to do. Callers write «… не удалось — .», so it ends without a full stop. + * A files-service problem told the way the user asked for (2026-10-11): the CAUSE first — white IP, + * ports or domain, so it's clear at a glance which one — then a plain «why», then what to do. + * Callers write «… не удалось — .», so it ends without a full stop. */ -const explain = (what: string, why: string, todo: string) => `${what}.\n\nПочему: ${why}.\n\nЧто сделать: ${todo}`; +const explain = (cause: string, why: string, todo: string) => `${cause}.\n\nПочему это мешает: ${why}.\n\nЧто сделать: ${todo}`; const WHY_PAGE = 'большие файлы передаются через страницу на вашем сервере'; -const WHY_CERT = `${WHY_PAGE}, а ей нужен HTTPS-сертификат. Его выдаёт Let's Encrypt — и перед выдачей проверяет, что адрес действительно ведёт на ваш сервер`; +/** What the page needs from the server — the yardstick every cause below is measured against. */ +const WHY_REACH = `${WHY_PAGE}, и она должна открываться из интернета — по белому IP-адресу сервера, на портах 80 и 443`; const NO_FILES = 'а если большие файлы не нужны — выключите их: FILES=off в .env'; /** Behind a router: reconcile.sh saw a private address on the server itself (its «nat» tag). */ -const NO_WHITE_IP = 'у сервера нет своего белого IP-адреса — он стоит за роутером, и из интернета до него не достучаться'; +const NO_WHITE_IP = 'у сервера нет белого IP-адреса'; +const NAT_WHY = `${WHY_REACH}. А этот сервер стоит за роутером, и из интернета до него не достучаться`; const NAT_TODO = `если у роутера белый IP — пробросьте на сервер порты 80 и 443 в настройках роутера. Если белого IP нет (провайдер выдаёт серый) — проброс не поможет: подключите белый IP у провайдера или поставьте мост на VPS; ${NO_FILES}`; +const PORTS_CLOSED = 'закрыты порты 80 и 443'; +const PORTS_WHY = `${WHY_REACH}. Белый IP у сервера есть, но порты 80 и 443 из интернета не открываются — обычно их закрывает файрвол хостинга`; +const PORTS_TODO = `откройте порты 80 и 443 в панели хостинга; ${NO_FILES}`; const LOG_HINT = 'Подробности — в /var/lib/telemax-files/reconcile.log на сервере'; export const SERVICE_TIMEOUT_TEXT = explain( - 'служба файлов не ответила за 2,5 минуты', - `${WHY_PAGE}, и порты 80 и 443 сервера должны открываться из интернета. Чаще всего они закрыты: сервер дома за роутером или их закрывает файрвол хостинга`, - `пробросьте на сервер порты 80 и 443 на роутере или откройте их в панели хостинга; ${NO_FILES}. ${LOG_HINT}`, + 'сервер не стал доступен из интернета за 2,5 минуты', + `${WHY_REACH}. Чаще всего мешает одно из двух: у сервера нет белого IP-адреса (он дома за роутером) или закрыты порты 80 и 443 (их закрывает файрвол хостинга)`, + `если сервер за роутером — нужен белый IP у роутера и проброс портов 80 и 443 на сервер; если это VPS — откройте порты в панели хостинга; ${NO_FILES}. ${LOG_HINT}`, ); -export const SERVICE_TIMEOUT_NAT_TEXT = explain('служба файлов не ответила за 2,5 минуты', `${WHY_PAGE}, и до сервера должен быть доступ из интернета. А ${NO_WHITE_IP}`, `${NAT_TODO}. ${LOG_HINT}`); +export const SERVICE_TIMEOUT_NAT_TEXT = explain(NO_WHITE_IP, NAT_WHY, `${NAT_TODO}. ${LOG_HINT}`); export class FileShare { readonly dir: string; @@ -541,48 +547,55 @@ export class FileShare { } /** - * service.json → what happened, why and what to do (see explain). reconcile.sh passes Caddy's ACME - * error through as «acme: urn:ietf:params:acme:error: - …» (English, maybe cut): the type - * decides first, the wording second. Pure + exported for tests. + * service.json → the cause, why it matters, what to do (see explain). reconcile.sh passes Caddy's ACME + * error through as «acme: [nat: ]urn:ietf:params:acme:error: - …» (English, maybe cut): the + * type decides first, the wording second. Pure + exported for tests. */ export function describeServiceProblem(st: { state?: string; detail?: string }): string { if (st.state === 'ports-busy') { return explain( - 'порты 80 и 443 на сервере уже заняты другим веб-сервером', + 'порты 80 и 443 заняты другим веб-сервером', `${WHY_PAGE}, и ей нужны эти порты`, `пустите файлы через ваш веб-сервер — FILES_PUBLIC_URL и FILES_LISTEN в .env (пример в README); ${NO_FILES}`, ); } if (st.state === 'no-ip') { - return explain('не удалось узнать внешний IPv4-адрес сервера', `${WHY_PAGE}, а ссылка на неё строится по адресу сервера`, 'укажите свой домен — FILES_DOMAIN в .env'); + return explain('не удалось узнать белый IP-адрес сервера', `${WHY_PAGE}, а ссылка на неё строится по IP-адресу сервера`, 'укажите свой домен — FILES_DOMAIN в .env'); } const detail = (st.detail ?? '').trim(); if (/^acme:/i.test(detail)) { const behindNat = /^acme:\s*nat:/i.test(detail); - const fail = (because: string, todo: string) => explain("Let's Encrypt не выдал серверу HTTPS-сертификат", `${WHY_CERT}. Проверка не прошла: ${because}`, todo); const unreachable = /acme:error:(connection|tls)\b|timeout during connect|firewall|connection refused|connection reset|no route to host|network unreachable/i.test(detail); const wrongAnswer = /acme:error:(unauthorized|incorrectresponse)\b|invalid response|status code 404|403 forbidden/i.test(detail); // A home server: no white IP of its own — the fix depends on the router and the provider. - if (behindNat && (unreachable || wrongAnswer)) return fail(NO_WHITE_IP, NAT_TODO); - if (unreachable) { - return fail('из интернета не открываются порты 80 и 443 сервера — скорее всего, их закрывает файрвол хостинга', `откройте порты 80 и 443 в панели хостинга; ${NO_FILES}`); - } + if (behindNat && (unreachable || wrongAnswer)) return explain(NO_WHITE_IP, NAT_WHY, NAT_TODO); + if (unreachable) return explain(PORTS_CLOSED, PORTS_WHY, PORTS_TODO); if (wrongAnswer) { - return fail( - 'на портах 80 и 443 по адресу сервера отвечает другой сервер', - `проверьте, что внешний адрес ведёт именно на этот сервер (например, не выходит ли он в интернет через VPN); ${NO_FILES}`, + return explain( + 'по IP-адресу сервера отвечает другой сервер', + `${WHY_REACH}. Но на этих портах отвечает не ваш сервер — например, если он выходит в интернет через VPN, его внешний адрес определился не тот`, + `проверьте, что внешний IP-адрес ведёт именно на этот сервер; ${NO_FILES}`, ); } if (/acme:error:dns\b|nxdomain|no valid a records|no such host|dns problem/i.test(detail)) { - return fail( - 'домен из настройки FILES_DOMAIN не указывает на этот сервер', + return explain( + 'домен из FILES_DOMAIN указывает не на этот сервер', + `${WHY_PAGE}, и ссылки на неё строятся на домене из настройки FILES_DOMAIN. Но домен не ведёт на ваш сервер, поэтому Let's Encrypt не выдал для него HTTPS-сертификат`, 'проверьте A-запись домена или уберите FILES_DOMAIN из .env — тогда ссылки пойдут по IP-адресу сервера', ); } if (/acme:error:ratelimited\b|ratelimit|rate limit|too many/i.test(detail)) { - return fail("было слишком много попыток, и Let's Encrypt временно ограничил выдачу для этого адреса", 'подождите час и попробуйте снова'); + return explain( + "Let's Encrypt временно не выдаёт сертификат", + 'страница для больших файлов работает по HTTPS, а сертификат для этого адреса запрашивали слишком часто', + 'подождите час и попробуйте снова', + ); } - return fail(detail.replace(/^acme:\s*/i, ''), `посмотрите /var/lib/telemax-files/reconcile.log на сервере; ${NO_FILES}`); + return explain( + "Let's Encrypt не выдал HTTPS-сертификат", + `страница для больших файлов работает по HTTPS. Ответ Let's Encrypt: ${detail.replace(/^acme:\s*(nat:\s*)?/i, '')}`, + `${LOG_HINT.replace('Подробности — в', 'посмотрите')}; ${NO_FILES}`, + ); } return `служба файлов не запустилась${detail ? `: ${detail}` : ''}`; } diff --git a/tests/fileShare.test.ts b/tests/fileShare.test.ts index b7818ac..65cf0a5 100644 --- a/tests/fileShare.test.ts +++ b/tests/fileShare.test.ts @@ -157,7 +157,7 @@ describe('FileShare.ensureService', () => { await service(share, 'ports-busy'); const r = await share.ensureService(1000); expect(r.ok).toBe(false); - expect(!r.ok && r.reason).toMatch(/порты 80 и 443 на сервере уже заняты/); + expect(!r.ok && r.reason).toMatch(/^порты 80 и 443 заняты другим веб-сервером/); }); it('says so when no host dispatcher serves this install', async () => { @@ -277,7 +277,8 @@ describe('files service problems in plain words', () => { detail: 'acme: error:HTTP 400 urn:ietf:params:acme:error:connection - 1.2.3.4: Timeout during connect (likely firewall problem)', }); expect(firewall).toContain('файрвол хостинга'); - expect(firewall).toContain('Почему:'); + expect(firewall.startsWith('закрыты порты 80 и 443.')).toBe(true); // the cause comes first + expect(firewall).toContain('Почему это мешает:'); expect(firewall).toContain('Что сделать:'); expect(firewall.endsWith('.')).toBe(false); // callers add the full stop expect(firewall).toContain('откройте порты 80 и 443 в панели хостинга'); @@ -287,15 +288,15 @@ describe('files service problems in plain words', () => { ); // Behind a router (reconcile.sh tags it «nat: »): say it has no white IP and what that means. const nat = describeServiceProblem({ state: 'error', detail: 'acme: nat: urn:ietf:params:acme:error:connection - 5.6.7.8: Timeout during connect' }); - expect(nat).toContain('нет своего белого IP'); + expect(nat.startsWith('у сервера нет белого IP-адреса.')).toBe(true); expect(nat).toContain('пробросьте'); expect(nat).toContain('серый'); expect(nat).toContain('FILES=off'); - expect(describeServiceProblem({ state: 'error', detail: 'acme: nat: urn:ietf:params:acme:error:unauthorized - x' })).toContain('нет своего белого IP'); + expect(describeServiceProblem({ state: 'error', detail: 'acme: nat: urn:ietf:params:acme:error:unauthorized - x' })).toContain('у сервера нет белого IP-адреса'); expect(describeServiceProblem({ state: 'error', detail: 'acme: nat: urn:ietf:params:acme:error:dns - NXDOMAIN' })).toContain('FILES_DOMAIN'); expect(describeServiceProblem({ state: 'error', detail: 'acme: error:DNS problem: NXDOMAIN looking up A for files.example.org' })).toContain('FILES_DOMAIN'); expect(describeServiceProblem({ state: 'error', detail: 'acme: error:urn:ietf:params:acme:error:rateLimited' })).toContain('подождите час'); - expect(describeServiceProblem({ state: 'error', detail: 'acme: msg:challenge failed oddly' })).toContain('Проверка не прошла: msg:challenge failed oddly'); + expect(describeServiceProblem({ state: 'error', detail: 'acme: msg:challenge failed oddly' })).toContain('Ответ Let\x27s Encrypt: msg:challenge failed oddly'); // What reconcile.sh really passes (live test 2026-10-11): the type first, the wording may be cut. expect(describeServiceProblem({ state: 'error', detail: 'acme: urn:ietf:params:acme:error:dns - DNS problem: NXDOMAIN looking up A for x' })).toContain('FILES_DOMAIN'); expect(describeServiceProblem({ state: 'error', detail: 'acme: urn:ietf:params:acme:error:connection - 1.2.3.4: Ti' })).toContain('файрвол хостинга');