99 lines
4.4 KiB
Markdown
99 lines
4.4 KiB
Markdown
<!-- 27a4a527-c3b0-4e37-b4ed-ba7e02f51f70 -->
|
||
---
|
||
todos:
|
||
- id: "composer"
|
||
content: "在 composer.json 增加 vcs repository 并 docker composer require quanfuxia/log:dev-main"
|
||
status: pending
|
||
- id: "logconfig"
|
||
content: "改写 config/log.php 使用 SeasLogHandler + SeasLogLineFormatter + IntrospectionProcessor"
|
||
status: pending
|
||
- id: "middleware"
|
||
content: "新增 app/middleware/TraceId.php 调用 TraceContext::init，并在 config/middleware.php 注册全局中间件"
|
||
status: pending
|
||
- id: "verify"
|
||
content: "php -l 校验、请求验证日志落盘，跑收尾门禁脚本"
|
||
status: pending
|
||
isProject: false
|
||
---
|
||
# 引入并配置 quanfuxia/log
|
||
|
||
## 背景
|
||
`quanfuxia/log`（`Quanfuxia\Log\`）是一个 Webman/Monolog → SeasLog 的日志适配库，核心组件：
|
||
- `SeasLogHandler`：Monolog 记录写入 SeasLog，自动 `SeasLog::setRequestID(traceId)`，BasePath 设为 `runtime_path()/logs`
|
||
- `SeasLogLineFormatter`：日志行格式化
|
||
- `Trace\TraceContext`：基于 `Webman\Context` 的 `trace_id` / `request_time` 上下文
|
||
|
||
环境已确认：`php82` 容器存在 `SeasLog` 扩展，PHP 8.2.24；库要求 `php>=8.2`、`monolog ^2.0`（项目已具备）。仓库仅有 `main` 分支、无 tag，故按 `dev-main` 引入。容器内项目路径 `/app/www/ai-device/ota`。
|
||
|
||
## 1. composer 引入（在 docker php82 内执行）
|
||
在 [composer.json](composer.json) 增加 `repositories` 与依赖：
|
||
|
||
- 顶层新增：
|
||
```json
|
||
"repositories": [
|
||
{ "type": "vcs", "url": "https://git.waixingkeji.net/quanfuxia/log.git" }
|
||
]
|
||
```
|
||
- `require` 增加 `"quanfuxia/log": "dev-main"`
|
||
|
||
执行安装（遵循 dev-environment 规则，宿主机不直接跑 composer）：
|
||
```bash
|
||
docker exec -w /app/www/ai-device/ota php82 composer require quanfuxia/log:dev-main
|
||
```
|
||
> 项目 `minimum-stability: dev` + `prefer-stable: true`，`dev-main` 可正常解析。私有仓库已验证可匿名 clone；若 composer 拉取需鉴权再补充凭据。
|
||
|
||
## 2. 配置 config/log.php
|
||
将 [config/log.php](config/log.php) 的 `default` channel 由 `RotatingFileHandler` 改为 `SeasLogHandler`，并加上 `IntrospectionProcessor` 注入调用源（`extra.class/function/file/line`）：
|
||
|
||
```php
|
||
use Monolog\Logger;
|
||
use Monolog\Processor\IntrospectionProcessor;
|
||
use Quanfuxia\Log\SeasLogHandler;
|
||
use Quanfuxia\Log\SeasLogLineFormatter;
|
||
|
||
return [
|
||
'default' => [
|
||
'handlers' => [[
|
||
'class' => SeasLogHandler::class,
|
||
'constructor' => ['level' => Logger::DEBUG, 'bubble' => true],
|
||
'formatter' => [
|
||
'class' => SeasLogLineFormatter::class,
|
||
'constructor' => [
|
||
"%message% %extra.class%%extra.callType%%extra.function% %extra.file%:%extra.line% %context%\n",
|
||
'Y-m-d H:i:s', true, true,
|
||
],
|
||
],
|
||
]],
|
||
'processors' => [[
|
||
'class' => IntrospectionProcessor::class,
|
||
'constructor' => [Logger::DEBUG, ['support\\Log'], 0],
|
||
]],
|
||
],
|
||
];
|
||
```
|
||
> [config/process.php](config/process.php) 中 `'logger' => Log::channel('default')` 无需改动，框架日志将随之写入 SeasLog。
|
||
|
||
## 3. 新增 Trace 中间件初始化 trace_id
|
||
每次 HTTP 请求开始时初始化链路 ID，使同一请求内日志 trace_id 一致，并支持上游透传。
|
||
|
||
- 新增 `app/middleware/TraceId.php`（实现 `Webman\MiddlewareInterface`）：从请求头（如 `X-Trace-Id`）取值，调用 `Quanfuxia\Log\Trace\TraceContext::init($headerTraceId)`，再 `return $handler($request)`。
|
||
- 在 [config/middleware.php](config/middleware.php) 注册为全局中间件：
|
||
```php
|
||
return [
|
||
'' => [ app\middleware\TraceId::class ],
|
||
];
|
||
```
|
||
> CLI / 非中间件入口无需额外处理：`TraceContext::getTraceId()` 在缺失时会自动生成并写回上下文。
|
||
|
||
## 4. 验证
|
||
```bash
|
||
docker exec -w /app/www/ai-device/ota php82 php -l config/log.php
|
||
docker exec -w /app/www/ai-device/ota php82 php -l app/middleware/TraceId.php
|
||
# 启动后请求一次接口，检查日志落盘
|
||
docker exec php82 sh -lc 'ls -R /app/www/ai-device/ota/runtime/logs'
|
||
```
|
||
并按 `slot-backend-completion-report` 跑收尾门禁。
|
||
|
||
## 注意 / 待确认
|
||
- `git_status` 显示 `composer.json`/`composer.lock` 已有 `vlucas/phpdotenv` 改动，本次只追加，不回退既有改动。
|
||
- 日志格式字符串、`X-Trace-Id` 头名称如需调整可后续微调（默认按 readme 示例）。 |