> 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.7.md).

# V2.0.7

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

## 概述

v2.0.7 将 V1 兼容路径的剩余硬编码限制移至部署环境变量。响应大小限制、超时值和 multipart 内存缓冲区现在在启动时读取一次，通过显式范围检查和超时关系规则进行验证，修改后需要重启才能生效。

启动验证确保 `IMGPROXY_REQUEST_TIMEOUT` 严格小于 `V1_GENERATION_TIMEOUT`，防止配置错误导致所有动态转换失败。

此版本不添加数据库架构版本，不更改 HTTP 或上传 API，也不更改图像处理配方。

## 变更内容

### V1 响应和超时限制

* `V1_DYNAMIC_MAX_RESPONSE_BYTES` 限制动态转换响应体大小。默认 100663296（96 MiB），范围 1 MiB 到 512 MiB。
* `V1_BACKGROUND_MAX_RESPONSE_BYTES` 限制后台格式转换响应体大小。默认 33554432（32 MiB），范围 1 MiB 到 256 MiB。
* `V1_GENERATION_TIMEOUT` 设置 imgproxy 操作的总生成超时。默认 35s，范围 5s 到 5m。
* `IMGPROXY_REQUEST_TIMEOUT` 设置 imgproxy 请求的 HTTP 客户端超时。默认 30s，范围 5s 到 5m，且**必须小于** `V1_GENERATION_TIMEOUT`。
* `V1_MULTIPART_MEMORY_BYTES` 设置 Gin multipart 表单内存缓冲区。默认 8388608（8 MiB），范围 1 MiB 到 64 MiB。

### 配置验证

* 为所有五个新变量添加启动验证，包含显式范围检查。
* **关键验证**：启动验证会拒绝 `IMGPROXY_REQUEST_TIMEOUT >= V1_GENERATION_TIMEOUT` 的配置，在连接 MySQL 或 Redis 之前返回清晰错误。这防止了每个动态转换都超时的静默失败。
* 超时关系确保 imgproxy 有时间完成并在调用者的上下文截止时间到期之前返回错误。

### 硬编码常量移除

* 从 `internal/handler/public_handler.go` 中移除常量 `v1DynamicMaximumResponseBytes`（96 MiB）、`v1BackgroundMaximumResponseBytes`（32 MiB）和 `v1GenerationTimeout`（35s）。
* `PublicHandler` 现在存储完整的 `ImageV1Config` 并将其用于所有限制检查和超时值。
* imgproxy HTTP 客户端超时从 `v1Limits.ImgproxyRequestTimeout` 设置，而不是硬编码的 30s。
* Gin 路由器的 `MaxMultipartMemory` 从 `cmd/server/main.go` 中的 `cfg.ImageV1.MultipartMemoryBytes` 设置。

### 可观测性

* 启动摘要现在记录一行包含五个新 V1 限制的附加内容：`v1_dynamic_max_response_bytes`、`v1_background_max_response_bytes`、`v1_generation_timeout`、`imgproxy_request_timeout` 和 `v1_multipart_memory_bytes`。

### 部署示例

* `backend/.env.example` 记录了每个新变量，并附有注释说明它们是启动时限制，经过验证，且永远不会通过管理员 API 暴露。

## 验证

* 后端 `go test ./...`：通过。更新了 `config_test.go` 和 `public_handler_test.go` 以初始化新的 V1 配置字段。
* 后端 `go vet ./...`：通过。
* 后端 `go build ./...`：通过。
* 前端 ESLint：通过（无前端更改）。
* 单元测试覆盖默认值、边界验证、超时关系验证（有效和无效排序）以及启动摘要包含新限制。
* Python requirements lock 验证：通过。
* GitBook 文档和翻译验证：通过。

## 安装

必须显式拉取开发镜像：

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

等效的精确开发标签：

```
jaykserks/summerain:dev-2.0.7
```

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

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

## 已知限制

* 这些限制在启动时读取一次；更改它们需要重启。
* V1 路径的响应大小限制和生成超时现在可配置，但默认值与 v2.0.6 及更早版本保持不变。
* 完整的固定图像配方仍然是服务器端关注点，计划在后续版本（阶段 3）中实现。
* 动画图像支持仍计划在后续版本中实现。

## 相关工作

此版本实现了 `PHASES-2-8-PLAN-v2.md` 的**阶段 2**：将 V1 剩余硬编码限制移至环境变量。

**下一阶段**：阶段 3（v2.0.8）将把图像配方外部化到 `config/image-recipe.json` 并生成用于生产部署的显式 SQL 迁移文件。


---

# 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.7.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.