> For the complete documentation index, see [llms.txt](https://summerain-1.gitbook.io/summerain/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://summerain-1.gitbook.io/summerain/zh-cn/fa-bu-shuo-ming/v2.0.11.md).

# V2.0.11

> 开发预发布版本。此版本从 `dev` 分支发布，可能会快速接收后续更改，不会被默认的 `latest` 镜像标签选择。

## 概述

v2.0.11 用有界、结构化的崩溃上报取代了前端最后几处控制台输出，由服务端写入日志。 React 渲染崩溃、未捕获错误与未处理的 Promise 拒绝现在会被去重、截断后上报一次， 而不再只留在浏览器控制台里。

该端点不保留数据库状态，按 IP 限流，并且永远不会收到 query 串、Cookie 或令牌。 前端 lint 现在会强制执行仓库的控制台禁令，此前该规则存在三处例外。

## 变更内容

### 后端端点

* 新增 `POST /api/v1/public/client-errors`：接收一条有界 JSON 上报，写入一行带请求 ID 的 `[client-error]` 日志。
* 上报类型仅限 `boundary`、`error` 与 `unhandledrejection`；消息为空或类型未知时返回 `3000`。
* 服务端统一截断字段：message 300 字节、stack 与 component\_stack 2000 字节、 source 与 path 200 字节、user agent 200 字节。
* 请求体上限 8 KiB（超出返回 `3002`）；每个 IP 每分钟最多 20 条，超出返回新增的错误码 `2091`(429) 并带 `Retry-After: 60`。Redis 故障沿用原有的 fail-closed 行为。
* 日志绝不记录 IP、Cookie 或令牌。

### 前端上报

* 新增 `lib/crash-report.ts`：与服务端一致的字段截断；仅上报路径（剥离 query 与 fragment， 私密图片令牌不会泄漏）；5 秒指纹去重；每页每分钟最多 3 次上报。
* 新增 `lib/global-crash-handlers.ts`，在启动时安装一次，用于上报未进入 React 错误边界的 未捕获错误与未处理的 Promise 拒绝。
* `ErrorBoundary` 改为通过 `reportClientCrash` 上报，不再使用 `console.error`； DOM 变异自愈重试逻辑保持不变。
* 删除图片列表删除流程中的两处调试 `console.error`。
* 新增 `no-console: error` ESLint 规则，并为测试保留显式豁免，使控制台禁令长期生效。

## 验证

* 后端 `go build ./...`、`go vet ./...`、`go test ./...`：通过。
* 前端 `npm run lint`、`tsc -b` 与 Vite 生产构建：通过。
* 前端 Vitest：21 个测试文件、160 个测试通过（此前为 18 个文件、148 个测试）。
* 新增覆盖：字段截断与类型校验、请求拒绝（413/400）、上报净化与截断、去重、每分钟预算、 传输失败隔离、全局错误与拒绝事件分发，以及错误边界的兜底、重试与上报路径。
* Python requirements lock 验证与 GitBook 文档验证：通过。

## 安装

必须显式拉取开发镜像：

```bash
docker pull jaykserks/summerain:dev-v2.0.11
```

等效的精确开发标签：

```
jaykserks/summerain:dev-2.0.11
```

移动的 `dev` 标签也指向最新的成功开发构建。`latest`、`main` 和稳定的语义版本别名 不受此版本影响。

从 v2.0.10 升级不需要数据库迁移或 API 迁移。

## 已知限制

* 上报只写入服务端日志，服务端不做聚合或告警。
* 该端点按设计是公开的，恶意客户端可以调用它；请求体上限与按 IP 限流限制了影响， 且上报内容不含任何认证输入。
* 动画图像支持仍计划在后续版本中实现。

## 相关工作

此版本以插入版本的形式实现了 `PHASES-2-8-PLAN-v2.md` 的**阶段 6**； 原阶段 6 与阶段 7 顺延为阶段 7 与阶段 8。

**下一阶段**：阶段 7（v2.0.12）完成 Docker 部署方案与三语文档。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://summerain-1.gitbook.io/summerain/zh-cn/fa-bu-shuo-ming/v2.0.11.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.