feat(log): 启动日志打印真实可访问地址,回环绑定时显式告警

绑定 0.0.0.0 时日志直接拼 http://0.0.0.0:3000——浏览器打不开,
排障时只会看到"已启动"却不知道访问哪个 IP。

- 新增 src/config/access-hint.ts:describeAccess() 把绑定地址翻译成
  监听描述 + 可访问地址(回环 / 具体网卡 / 通配取真实网卡 IPv4);
  独立成模块是为了可测——main.ts 顶层会执行 bootstrap(),不能被 import
- main.ts:启动日志改为「监听 …(全部网卡,外部可访问)」+ 真实访问地址;
  HOST=127.0.0.1 时用 warn 明确提示"只能本机访问"并给出修复方法
- 新增 test/access-log.spec.ts(4 项)覆盖三种绑定模式,
  断言通配模式绝不出现 0.0.0.0 形式的 URL

实测三种模式日志输出正确;单测 35/35、契约与 29 条路由校验通过。
This commit is contained in:
2026-09-15 02:04:51 +08:00
parent 44451028dd
commit 76725e5ce3
3 changed files with 94 additions and 3 deletions
+15 -3
View File
@@ -5,6 +5,7 @@ import { NextFunction, Request, Response } from 'express';
import { existsSync, mkdirSync } from 'node:fs';
import { extname, join, resolve } from 'node:path';
import { AppModule } from './app.module';
import { describeAccess } from './config/access-hint';
import { AppConfig, configuration, validateEnv } from './config/configuration';
async function bootstrap(): Promise<void> {
@@ -90,13 +91,24 @@ async function bootstrap(): Promise<void> {
const db = config.db;
await app.listen(config.port, config.bindHost);
logger.log(`OpenDance Studio Web 服务端已启动:http://${config.bindHost}:${config.port}`);
logger.log(`健康检查:http://${config.bindHost}:${config.port}/health`);
const access = describeAccess(config.bindHost, config.port);
const externalUrls = access.urls.filter((url) => !url.includes('127.0.0.1'));
logger.log(`OpenDance Studio Web 服务端已启动,监听 ${access.listen}`);
if (access.loopbackOnly) {
logger.warn(
`可访问地址:${access.urls[0]}(只能本机访问;` +
'要让外部访问,请在 .env 中设置 HOST=0.0.0.0 后重启)',
);
} else if (externalUrls.length > 0) {
logger.log(`可访问地址:${externalUrls.join('、')}(管理端页面与 API 同一端口)`);
}
logger.log(`健康检查:${externalUrls[0] ?? access.urls[0]}/health`);
logger.log(`数据库:${db.host}:${db.port}/${db.name}(现有实例,本服务不管理 MySQL)`);
logger.log(`文件存储:${storageDir}`);
logger.log(
existsSync(adminIndex)
? `管理端站点:http://${config.bindHost}:${config.port}/(由本服务直接提供)`
? `管理端站点:${externalUrls[0] ?? access.urls[0]}/(由本服务直接提供)`
: '管理端站点:未部署(仅 API)',
);
logger.log(`契约版本:${JSON.stringify(config.contractVersions)}`);