LogShare 是一个面向 Minecraft 与 Hytale 等沙盒游戏的高性能日志智能分析与安全分享云平台。使用者通过 HTTP 接口上传服务端、客户端日志或崩溃转储包，即可获得高可用分享链接；系统采用极速上传解耦设计，上传时仅执行轻量 Codex 特征检测并毫秒级响应，将高耗时的 SpinYarn 混淆堆栈反解与全量敏感内容审核交由**统一异步事件队列（EventQueue）**排队调度处理。
在此之上，平台搭载工业级解耦重构的 LogAgent 智能排障诊断引擎，内建 deep（深度推理排障）、launcher（启动器崩溃优先）与 quick（极速直答）三种分析模式。支持自主调度 Exa 多源网络搜索、内置本地向量与全文检索（RAG）、日志精确定位检索及 GitHub 启动器排障工具链，结合动态日志窗口（LogWindowManager）聚焦真实崩溃上下文，以 SSE 流式输出思维链、排障建议及严格结构化 JSON 诊断块，并由四维评估引擎（AnalysisScorer）与链路追踪系统（AnalysisTracer）保障诊断质量。
服务端基于 Hyperf 3.2 框架与 Swoole 6.2 高性能协程常驻进程引擎，原生要求 PHP 8.4 及以上。存储后端支持 MariaDB 与文件系统二选一，Redis 作为缓存、限流与事件流消息总线。当前版本 v1.8.2-beta.2，更新记录见 CHANGELOG.md。
- PHP 8.4+，扩展 ext-json、ext-zlib、ext-mbstring、ext-pdo_mysql、ext-pdo_sqlite
- Swoole 6.2（常驻进程运行时）
- MariaDB 或文件系统（主要存储，二选一）
- Redis（可选，用于缓存、限流与统一异步事件队列；缺少 ext-redis 时以内置 mock 优雅降级）
- SQLite（RAG 知识库检索）
- SpinYarn 扩展（可选，原生 Rust 编写，用于混淆堆栈反解；缺失时日志原样透传）
composer install
cp Config.inc.example.php Config.inc.php
php bin/hyperf.php startConfig.inc.php 是唯一的应用配置文件（已被 Git 忽略），数据库与 Redis 连接信息可通过 DB_*、REDIS_* 环境变量覆盖。服务监听 9501 端口；内置 RAG 的 MCP 服务承载于同一进程的 /rag 路径，默认仅允许本机回环访问。
Config.inc.php 的主要配置段：
| 配置段 | 说明 |
|---|---|
storage |
存储后端（MariaDB 与文件系统二选一）、日志保留时间（TTL）、多文件与 ZIP 上传限制（uploadFiles） |
cache |
Redis 缓存：开关、TTL、大小限制与连接信息 |
filter |
上传前的预处理过滤链（脱敏规则），按配置顺序执行 |
id |
日志 ID 的字符集与长度（修改会破坏已有 ID） |
security |
动态合规防护：AES-256-GCM 密文存储违规关键词与正则、IP 黑名单与反向代理真实 IP 判定 |
eventQueue |
统一日志事件队列：Redis Stream 键名与消费组、最大重试次数、异步反混淆与异步安全审核开关 |
ai |
AI 分析核心：API Key 轮询列表、模型、agent（LogAgent 开关）、queue（Redis Streams 分析微队列）、rag（bge-m3 语义向量增强与故障转移） |
github |
启动器/渲染器排障工具：多 Personal Access Token 轮询、速率限制感知、403/429 自动冷却故障切换 |
rateLimit |
应用层限流（limit / window，Redis INCR 实现） |
spinyarn |
反混淆扩展：映射目录与缓存水位 |
admin |
管理后台开关与安全 Token（/{version}/admin/* 控制台鉴权） |
urls |
前端与 API 的基础 URL |
仓库以 submodule 引用边缘 WAF（
OpenLiteWaf/，独立仓库 NingZeStudio/OpenLiteWaf，MIT）。clone 后先执行git submodule update --init --recursive；已部署机器可git config submodule.recurse true让后续git pull自动跟随 submodule 更新。
docker compose -f docker/compose.yaml up -d --build启动前先将 .env.example 复制为 .env 并填写数据库密码与 API Key。.env 由 Hyperf 进程读取，同时供 Compose 初始化 MariaDB 与 Redis 服务，其中 MARIADB_PASSWORD、MARIADB_ROOT_PASSWORD 与 REDIS_PASSWORD 必须在 Hyperf、MariaDB、Redis 与定时清理服务之间保持一致。AI 默认关闭；只有同时设置 AI_ENABLED=true、AI_API_KEYS、AI_BASE_URL 和 AI_MODEL 后才会启用，语义 RAG 启用时还要求 AI_RAG_PROVIDERS 为合法的 JSON 数组。
完整的业务配置（推理密钥、语义 RAG 供应商、生产域名）通过挂载项目根目录的 Config.inc.php 注入容器，服务器上放置好该文件后执行上面的命令即可。该文件包含密钥，已被 Git 与 Docker 构建上下文排除，只需在服务器上手动放置，不要提交进仓库。挂载后 AI 配置以文件为准；DB_* 与 REDIS_* 的容器网络寻址仍由 compose 环境变量提供。
Compose 定义五个服务：nginx（OpenResty 反向代理，对外监听 80/443，承载 OpenLiteWaf 与 TLS 证书）；hyperf（应用主进程，仅在内部网络监听 9501，启动时自动构建 RAG 索引，构建采用临时数据库加原子替换，失败时保留旧索引）；mariadb（数据存储，表结构由 docker/mariadb-init.sql 在首次创建卷时初始化）；mariadb-events（在数据库可用后创建过期日志清理 Event）；redis（缓存与限流）。
OpenLiteWaf（OpenLiteWaf/）是 nginx 容器内的 OpenResty Lua 模块，在反向代理层做按 IP 的固定窗口 CC 限速（超限返回 429，不封 IP）与攻击特征检查（SQL 注入、XSS、路径穿越、命令执行、扫描器探测）；检查范围包括 URL 原始与解码形态、请求路径、User-Agent 和请求体（接收任意用户文本的日志、分析、遥测与管理端点豁免请求体扫描），特征命中返回 403 并按窗口累计次数封禁 IP（默认累计 3 次才封，避免一次误判让该来源十分钟内在所有端点不可用）。统计页 https://<域名>/security（JSON 汇总：/security/stats，攻击日志分页：/security/logs，现存封禁与封禁原因：/security/bans）展示内存计数与脱敏后的攻击记录，含命中的规则序号与匹配对象；计数与封禁都会快照到挂载目录，重启后恢复（即“重启不是解封手段”）。误封的运行时解封走特权端点 POST /security/unban，令牌为 .env 中的 OPENLITEWAF_ADMIN_TOKEN，未配置时该端点一律 404。工作方式、配置与规则编写见 OpenLiteWaf/README.md；改动 Lua 文件后执行 docker compose -f docker/compose.yaml restart nginx 生效（git pull 只更新文件，不重载不生效；容器内 nginx -s reload 在本部署不可靠）。应用层安全由 Hyperf 负责，参数化查询、输出转义与脱敏过滤链不依赖本模块。
将 docker/nginx/default.conf 中两个 server_name 改为实际域名，并将 HTTPS 证书路径中的域名同步修改。首次签发前，先临时注释 HTTPS server 并启动 nginx，然后执行：
docker compose -f docker/compose.yaml run --rm acme certonly --webroot -w /var/www/acme -d api.example.com --email admin@example.com --agree-tos --no-eff-email恢复 HTTPS 配置后重新加载 nginx：
docker compose -f docker/compose.yaml up -d nginx
docker compose -f docker/compose.yaml exec nginx nginx -s reloadacme 容器每 12 小时检查续期，续期完成后需要执行一次 nginx reload 使新证书生效。证书目录不提交到 Git；域名需解析到服务器且公网开放 80 端口。
MariaDB 的 Event Scheduler 每小时删除超过 Config.inc.php 中 storage.storageTime 秒的日志，默认 604800 秒（7 天）。仓库内的 docker/mariadb-events.sql 是与默认 TTL 对应的默认版本，由 mariadb-events 服务在数据库可用后执行；修改 TTL 后先执行 php scripts/sync_mariadb_events.php 重新生成该 SQL，再重启 mariadb-events 服务，重新生成的文件按需提交以保持与部署一致。可用以下命令检查 Event 是否启用及下次执行时间：
docker compose -f docker/compose.yaml exec mariadb mariadb -uroot -p"$MARIADB_ROOT_PASSWORD" logshare -e "SHOW EVENTS LIKE 'cleanup_expired_logs'\\G"mariadb 的 healthcheck 也会验证该 Event 存在且状态为 ENABLED。MariaDB 使用固定名称的卷 logshare-mariadb-data，重建容器不会删除数据；不要执行 docker compose down -v，否则持久化卷会被删除。生产环境禁止使用默认密码，建议通过部署环境或 Docker secrets 注入凭据。
直接运行 php bin/hyperf.php start 并使用任意反向代理转发到 9501 即可，nginx 参考配置：
location / {
proxy_pass http://127.0.0.1:9501;
proxy_buffering off;
proxy_read_timeout 300s;
}同时提供 /1/（已弃用）与 /v1/ 两组路径，响应格式统一为 JSON（/raw 端点返回纯文本），建议新集成使用 /v1/。完整规范见 API.md、openapi.yaml 与 postman_collection.json。
POST /1/log | /v1/log 上传日志（极速解耦，支持多文件与 ZIP）
DELETE /1/log/{id} | /v1/log/{id} 删除日志（Bearer Token 鉴权）
GET /1/raw/{id} | /v1/raw/{id} 获取原始日志（主文件）
GET /v1/raw/{id}/{filename} 获取指定子文件（支持子路径）
GET /1/log/{id} | /v1/log/{id} 获取日志元信息与文件列表
GET /1/insights/{id} | /v1/insights/{id} 获取 Codex 结构化分析结果
POST /1/analyse | /v1/analyse 直接分析日志内容（不存储）
GET /1/ai/{id} | /v1/ai/{id} AI 智能诊断（SSE 流式，支持 mode 与 promptVersion 参数）
POST /1/ai/analyse | /v1/ai/analyse 提交内容直接分析（不落盘，SSE）
POST /v1/telemetry/report 上报客户端与启动器遥测指标
GET /1/limits | /v1/limits 获取速率限制信息
GET /1/filters | /v1/filters 获取当前启用的过滤器列表
/* /v1/admin/* 管理后台控制台（含全套 LogAgent 追踪与治理，需 Admin Token）
上传接口接受 application/x-www-form-urlencoded 与 application/json，支持 gzip / deflate / brotli 压缩请求体；files 数组可附加多个文件，.zip 压缩包自动展开并保留内部相对路径，展开后每个文件独立经过脱敏过滤链。客户端接入时遵循最佳实践规范：尽可能同时上传「游戏主日志 + 崩溃报告 + 启动器日志」并注明 source 来源标识，便于 AI 诊断引擎与社区准确定位启动器及渲染器环境引发的深层异常。上传响应中的 token 是删除该日志的唯一凭证。AI 分析使用 SSE 流式输出，LogAgent 支持 deep（深度排障）、launcher（启动器崩溃优先）和 quick（极速直答）三种模式，可自主调度 Exa 搜索、RAG 检索、日志精准定位检索及 GitHub 启动器排障工具，诊断结论附带结构化 JSON 卡片；Admin 端提供完整的分析追踪（Trace 归档/导出）、质量评分看板（Scoreboard）、Prompt 版本热更新及工具链门控。AI 关闭时相关端点统一返回 404。
bin/hyperf.php 入口文件（Hyperf Application）
core.php 引导文件（定义 CORE_PATH 并加载 Config）
app/ 核心类库（App\ 命名空间）
├── Agent/ LogAgent（多轮排障引擎、提示词版本化、工具链管理与质量追踪）
│ ├── Context/ AgentContext / ToolSession（会话上下文与工具状态链）
│ ├── Gateway/ AIClientGateway / LlmGateway / LlmStreamHandler（LLM 调用网关与故障转移）
│ ├── Quality/ AnalysisScorer / ResultValidator（四维质量评分与结构化结果验证）
│ ├── Tool/ ToolRegistry / ToolFactory / ToolInterface（9 大排障工具注册表与降级网关）
│ ├── Window/ LogWindowManager（自适应动态日志窗口与报错锚点聚焦）
│ ├── AgentRuntime.php 多轮工具循环引擎与分层停止条件控制
│ ├── AnalysisMode.php 排障模式（deep / launcher / quick）与动态预算控制
│ ├── AnalysisRecordManager.php 分析记录与 Trace 归档持久化（Redis ZSET 索引）
│ ├── AnalysisTracer.php 全链路执行追踪器（逐轮工具耗时、报错与指标）
│ ├── PromptBuilder.php 提示词模板构建与动态知识注入
│ ├── PromptManager.php 提示词版本库热管理与在线激活
│ └── ToolManager.php 排障工具链在线门控与 Fallback 降级配置
├── Cache/ Redis 缓存实现与协程连接池
├── Client/ AI、MCP、GitHub、Redis、SpinYarn 客户端
├── Command/ Hyperf 命令（rag:build 等）
├── Controller/ HTTP 控制器（注解路由，含 Log、AI、Admin 控制台等）
├── Data/ 数据模型（Token、MetadataEntry）
├── Filter/ 预处理过滤链（敏感信息脱敏）
├── Middleware/ CORS、AdminAuth、限流中间件
├── Parser/ 请求体解码（Brotli / Gzip / Deflate 自动解压与炸弹防护）
├── Process/ 常驻消费者进程（AiQueueConsumer、EventQueueConsumer）
├── Queue/ 统一日志异步事件队列（EventQueue、QueueEvent、DeadLetterQueue、Handler/）
├── Rag/ 本地 RAG 检索引擎（SQLite FTS5 + 语义向量召回）
├── Response/ 统一响应结构封装（ApiResponse）
├── Sse/ SSE 流式输出封装（SseWriter、AnalysisEmitter）
├── Storage/ 持久化存储后端（MariaDbStorage、FilesystemStorage）
├── System/ 系统核心服务（SecurityService、AuditLogManager、TelemetryService、SpinYarnManager）
├── ApiError.php API 业务异常（ApiExceptionHandler 统一渲染）
├── Config.php 配置加载器、环境变量覆盖与动态热重载引擎
├── ContentParser.php 请求正文与启动器特征识别
├── Detective.php 日志类型与服务端版本探测
├── UploadParser.php 多文件安全校验与 ZIP 展开引擎
├── Log.php 日志核心模型与反混淆持久化
└── Id.php ID 生成与存储后端编解码
config/autoload/ Hyperf 框架配置（server、databases、middlewares 等）
rag/ 内置 RAG：knowledge/ 静态知识库，index.db 索引（构建生成，勿提交）
docker/ Compose 编排、nginx 站点配置、镜像构建
OpenLiteWaf/ 边缘 WAF 独立子模块（OpenResty Lua，CC 防御与攻击特征拦截）
OpenLiteStats/ 边缘站点访问统计独立子模块（无锁位图 UV、流量统计与日志分析）
Config.inc.php 全部配置（gitignored）
Config.inc.example.php 配置模板
.env.example 环境变量模板（数据库、Redis、AI、Admin 秘钥覆盖）
AGENTS.md 项目核心架构约定与上下文文档
API.md 完整 API 文档
CHANGELOG.md 更新日志
docs/ 历史过程文档与设计规划
- 上传：
POST /v1/log→ RequestParser 解压请求体 → UploadParser 校验并展开 ZIP → 过滤链快速脱敏 → 执行轻量 Codex 特征分析 → 写入 MariaDB / 文件系统与 Redis 缓存 → 即刻派发EVENT_LOG_UPLOADED事件 → 毫秒级向客户端返回 200 响应。 - 异步流水线处理：常驻进程
EventQueueConsumer拉取事件 → 执行SecurityAuditHandler（主正文与全部附件敏感规则检测，若违规即刻物理清除日志、记录审计日志并封禁恶意 IP，阻断后续流转）→ 执行DeobfuscateHandler（调用 SpinYarn 原生反混淆并原子回写存储与刷新缓存）→ 异常自动重试，耗尽转入死信流events:log:dead。 - 读取：
GET /v1/raw/{id}（或子文件路径）→ Redis 缓存查询（如启用）→ 未命中时回源存储 → TTL 续期。 - 分析：
GET /v1/insights/{id}→ 加载日志 → Detective 检测服务端类型与版本 → Codex 引擎解析 → 格式化输出。 - AI 分析：
GET /v1/ai/{id}→ AI 微队列入队与中继 → LogAgent 工具循环 → LLM 流式推理 → 自主调度 Exa 搜索、RAG 知识检索、日志定位与 GitHub 排障 → SSE 推送思维链与结论。 - 删除：
DELETE /v1/log/{id}→ Bearer Token 鉴权（SHA-256 哈希比对）→ 删除存储与缓存。
日志 ID 为 7 位字符，首字符编码存储后端类型：s 表示 MariaDB，f 表示文件系统；其余 6 位为随机字符。字符集与长度可配置，但修改会破坏所有已有 ID，配置项 id.characters 与 id.length 不应改动。
公开流量的限速由边缘承担：nginx limit_req（30r/s burst=60）与 OpenLiteWaf 的 CC 封禁（10 秒窗口 240 次，超限封禁 IP 600 秒）。仓库中存在 RateLimitMiddleware（Redis INCR 按应用层计数，默认 600 次/60 秒，键为 IP + 方法 + 归一化路径，动态资源段折叠共享计数桶），但当前未注册到中间件链，属预留实现；如启用需注意其 Redis 故障路径为返回 503（fail-closed），与注释中的 fail-open 描述不符，见 app/Middleware/RateLimitMiddleware.php。
composer test # Pest 测试套件
composer test:architecture # Pest 架构约束测试
composer stan # PHPStan 静态分析（level 5）测试覆盖过滤器、存储、上传解析、MCP 客户端、LogAgent 工具循环、RAG 检索、Controller 集成与架构约束。存储链路的集成测试需要本地 MariaDB 与 Redis（可用 docker compose -f docker/compose.yaml up -d 启动）。Termux 环境运行 PHPStan 需加前缀 PHPSTAN_TURBO=0。OpenLiteWaf 有独立的回归测试，见 OpenLiteWaf/README.md。
在 app/Controller/ 中新增控制器，通过注解声明路由：
#[Controller(prefix: '/{version:v?1}')]
class ExampleController extends AbstractController
{
#[GetMapping(path: 'example')]
public function example(): ResponseInterface { ... }
}/{version:v?1} 前缀同时匹配 /1/ 与 /v1/；路径参数支持 {param}（单段）与 {param:.+}（含斜杠的通配段，用于子文件名）。
php bin/hyperf.php rag:build # 扫描 rag/knowledge/ 构建 SQLite FTS5 索引索引构建使用临时数据库，完成后原子替换正式索引，失败时保留旧索引；Docker 部署时 hyperf 容器启动命令会自动执行（幂等）。数据库路径由 ai.mcp.rag.db 指定，默认 rag/index.db。
知识库为手工维护的诊断资产（日志分析/patterns/format/android-native-lib/mobile_launcher 五个目录），易过期的启动器实战与各 ModLoader/服务端开发文档已移除，由 LogAgent 的 GitHub 实时排障工具链提供动态支撑；站点运营文案与测试素材位于索引之外。检索切块单元是 ## 二级标题，无标题的大文件须手工分段。新增知识目录须同步登记 RagSearch::TOPIC_DESCRIPTIONS。召回质量以金标集验收：php scripts/rag_eval.php（口径与指标见 rag/README.md）。语义 RAG 开启后需重新执行 rag:build 生成分块向量。
MIT