yedir-ai 运维与质量门禁

本文档记录日常开发、合并前检查、性能烟测和常见故障处理方式。

合并前检查

pnpm lint
pnpm check:logs
pnpm exec tsc --noEmit --pretty false
git diff --check

污染物检查：

git ls-files | rg '(^|/)\\.DS_Store$|\\.swp$|\\.env\\.local$|^\\.claude/|^migration-backup|^tsconfig\\.tsbuildinfo$' || true

预期无输出。

CI

.github/workflows/lint.yml 是基础质量门禁，负责 lint、日志治理、类型检查、diff hygiene 和 tracked 污染物检查。

Playwright workflow 独立运行，避免 e2e 依赖、浏览器安装和 secrets 影响基础门禁反馈速度。

日志治理

新增或修改已治理文件时不要使用裸 console.*。使用：

import { createLogger } from "@/lib/observability/logger";

const logger = createLogger("scope-name");
logger.info("event name", { count: 1 });
logger.error("event failed", error);

客户端使用 createClientLogger。生产环境默认静默，除非显式设置 NEXT_PUBLIC_ENABLE_CLIENT_LOGS=true。

pnpm check:logs 会检查已治理文件是否重新引入裸 console，并验证 token、API Key、URL、base64、password 等敏感值不会明文输出。

首页性能烟测

AUTH_TRUST_HOST=true PORT=3001 pnpm dev
curl -I --max-time 30 http://127.0.0.1:3001/
curl -I --max-time 30 "http://127.0.0.1:3001/api/site-settings?scope=home"
curl -I --max-time 30 "http://127.0.0.1:3001/api/featured?page=1&pageSize=24"

首页 HTML 应快速返回。公开轻量接口在数据库慢或不可用时应快速返回缓存或 fallback，不应长时间挂住首屏。

路由回归烟测

curl -I http://127.0.0.1:3001/
curl -I http://127.0.0.1:3001/classic
curl -I http://127.0.0.1:3001/chat/test-id
curl -I http://127.0.0.1:3001/settings
curl -I -X POST http://127.0.0.1:3001/api/files/upload

预期：

/ 返回 200。
/classic 和 /chat/test-id 返回 307 到 /。
/settings 未登录返回 307 到 /login?callbackUrl=%2Fsettings。
上传接口未登录返回 401。

常见故障

.next/dev/lock 阻止启动：已有 dev server 持锁，先确认进程归属，不要误杀其他工作区服务。
首页接口慢：先看 Server-Timing、X-Cache、X-Fallback，再查数据库连接池和公开接口 fallback。
登录 Host 错误：生产配置 AUTH_URL；仅在可信代理后设置 AUTH_TRUST_HOST=true。
上传失败：确认后台存储配置、环境变量 S3 fallback 或 BLOB_READ_WRITE_TOKEN 至少一组可用。
日志泄露风险：不要把完整 prompt、OAuth token、签名 URL、cookie、request body 放进日志 message。

2.7 KiB Raw Blame History Unescape Escape