ray604638018/cursor

Fork 0

Files

ray zhou 2dd9f17da9 ok

2026-06-29 14:51:55 +08:00

4.4 KiB

Raw Blame History

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 增加 repositories 与依赖：

顶层新增：

"repositories": [
  { "type": "vcs", "url": "https://git.waixingkeji.net/quanfuxia/log.git" }
]

require 增加 "quanfuxia/log": "dev-main"

执行安装（遵循 dev-environment 规则，宿主机不直接跑 composer）：

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 的 default channel 由 RotatingFileHandler 改为 SeasLogHandler，并加上 IntrospectionProcessor 注入调用源（extra.class/function/file/line）：

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 中 '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 注册为全局中间件：

return [
    '' => [ app\middleware\TraceId::class ],
];

CLI / 非中间件入口无需额外处理：TraceContext::getTraceId() 在缺失时会自动生成并写回上下文。

4. 验证

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 示例）。

4.4 KiB Raw Blame History Unescape Escape