93 lines
3.2 KiB
Markdown
93 lines
3.2 KiB
Markdown
# yedir-ai 运维与质量门禁
|
||
|
||
本文档记录日常开发、合并前检查、性能烟测和常见故障处理方式。
|
||
|
||
## 合并前检查
|
||
|
||
```bash
|
||
pnpm lint
|
||
pnpm check:logs
|
||
pnpm exec tsc --noEmit --pretty false
|
||
git diff --check
|
||
pnpm check:artifacts
|
||
```
|
||
|
||
等价的一键质量门禁：
|
||
|
||
```bash
|
||
pnpm check:quality
|
||
```
|
||
|
||
其中 `pnpm check:artifacts` 会检查 `.DS_Store`、swap 文件、`.env.local`、`.claude/`、migration backup 和 `tsconfig.tsbuildinfo` 等本地污染物是否被 Git 追踪。
|
||
|
||
## CI
|
||
|
||
`.github/workflows/lint.yml` 是基础质量门禁，运行 `pnpm check:quality`，负责 lint、日志治理、类型检查、diff hygiene 和 tracked 污染物检查。
|
||
|
||
CI 和本地提交前检查复用同一个入口，避免规则漂移。
|
||
|
||
Playwright workflow 独立运行，避免 e2e 依赖、浏览器安装和 secrets 影响基础门禁反馈速度。
|
||
|
||
Dependabot 每周检查 npm/pnpm 依赖和 GitHub Actions。依赖 PR 仍需按 PR 模板运行 `pnpm check:quality` 和路由烟测，不应自动合并。
|
||
|
||
## 日志治理
|
||
|
||
新增或修改已治理文件时不要使用裸 `console.*`。使用：
|
||
|
||
```ts
|
||
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 等敏感值不会明文输出。
|
||
|
||
## 首页性能烟测
|
||
|
||
```bash
|
||
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，不应长时间挂住首屏。
|
||
|
||
## 路由回归烟测
|
||
|
||
推荐使用脚本化检查：
|
||
|
||
```bash
|
||
AUTH_TRUST_HOST=true PORT=3001 pnpm dev
|
||
SMOKE_BASE_URL=http://127.0.0.1:3001 pnpm smoke:routes
|
||
```
|
||
|
||
手动检查等价命令：
|
||
|
||
```bash
|
||
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。
|