日志与诊断
本页聚合日志策略、诊断入口、运行期定位与问题排查入口。
适用场景
- 生产环境问题排查。
- 请求链路、错误定位、WorkContext 与 Activity 追踪。
- 诊断端点和后台管理入口保护。
必须遵守
- 诊断页与后台入口必须受认证或网络边界保护。
- 错误响应与日志职责分离：客户端拿规范化错误，详细信息进日志。
- 非 HTTP 执行流也要建立可追踪的上下文。
推荐做法
- 在 WebAPI 场景中统一异常处理与日志输出。
- 利用 WorkContext、Activity、请求会话信息对齐 TraceId。
- 发布前检查
/fwdev、/req_stat、/jobs暴露范围。
版本查看
框架里和“版本”相关的诊断入口至少有两类，它们解决的不是同一个问题：
/fwdev/ASSEMBLY_VERSIONS：查看当前节点实际加载的程序集版本，适合确认 DLL 是否已经按预期替换。/fwdiag/v：查看当前发布版本号，适合确认这台节点现在跑的是哪一次构建。
/fwdiag/v 这条链路依赖 MapDiagnosticRequest() 注册的诊断入口，以及运行目录下的 version.txt 文件。VersionTools 会从 AppContext.BaseDirectory/version.txt 读取版本号并返回给调用方。
这类版本查看最适合 Docker 发布的 ASP.NET WebAPI / Web 宿主项目：CI/CD 先在 dotnet publish 产物目录写入 version.txt，再由 Dockerfile 随最终发布目录一起复制进镜像，容器启动后 /fwdiag/v 就能直接返回当前镜像内的发布版本号。其他不走 Docker 的宿主只要也把 version.txt 放进运行目录，同样可以复用这条链路。
使用前要确认：
- 应用已经注册
MapDiagnosticRequest()。 - 运行目录中确实存在
version.txt。 - 如果没有写入该文件，
/fwdiag/v可能返回空字符串或无内容。
常见坑
- 在错误响应里直接暴露完整堆栈。
- 后台任务没有建立上下文，导致日志链路断裂。
- 诊断端点默认裸露到公网。
- 把
/fwdev/ASSEMBLY_VERSIONS和/fwdiag/v当成同一种版本信息，结果排查时看错对象。 - 镜像 tag 已经带版本号，但运行目录里没有
version.txt，导致容器内无法通过/fwdiag/v查看当前发布版本。
真实用例
- niusys-webapi：异常过滤器、
/jobs鉴权、Swagger 对齐。 - woscm：项目级异常处理器、TraceId 回写、公共管道中间件。