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

# V2.0.5

> 开发预发布版本。此版本从 `dev` 分支发布，后续修改可能较为频繁， 并且不会被默认的 `latest` 镜像选中。

## 概述

v2.0.5 明确了各类配置来源之间的职责边界。部署设置保留在环境变量中， 固定图片配方保留在服务器端，只有管理员管理的业务设置可以继续通过现有配置 API 写入。

管理员配置 API 现在会在开启数据库事务之前校验显式白名单。未知配置键以及部署级、 协议级配置键不会再被写入 `system_configs`，而是直接拒绝。

此版本不新增数据库结构版本，不改变 HTTP 或上传 API，也不改变图片处理配方。

## 变更

### 管理员配置白名单

* 新增唯一的可写系统配置白名单：`site_language`、`captcha_provider`、 `captcha_site_key`、`captcha_secret`、`private_token_ttl_default_ms`、 `watermark_*` 和 `r2_*`。
* 在任何数据库事务开始之前拒绝未知配置键。
* 拒绝 `DB_*`、`REDIS_*`、`V1_*`、`V2_*`、`IMGPROXY_*`、`MAX_JSON_BODY_BYTES` 等部署级、协议级配置键以及图片配方相关配置键。
* 空配置键会返回参数错误。
* 保留现有 CAPTCHA、R2 和水印的专项校验规则。

### 测试

* 覆盖允许写入的业务配置、被拒绝的部署级与协议级配置键，以及空键拒绝。

## 验证

* 后端 `go test ./...`：通过。
* 后端 `go vet ./...`：通过。
* 后端 `go build ./...`：通过。
* 前端 ESLint 与 Vite 生产构建：通过。
* 前端 Vitest：17 个测试文件，131 个测试通过。
* Python requirements 锁文件校验：通过。
* GitBook 文档与翻译校验：通过。
* 现有 wasm-vips 依赖的 direct-eval 警告保持不变，不会导致构建失败。

## 安装

开发镜像必须显式拉取：

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

等效的精确开发标签：

```
jaykserks/summerain:dev-2.0.5
```

滚动的 `dev` 标签也会指向最新一次成功的开发构建。此版本不会修改 `latest`、`main` 以及稳定的语义化版本别名。

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

## 已知限制

* 本白名单只约束管理员配置 API。启动级环境变量仍在进程启动时读取一次。
* 完整的固定图片配方仍属于服务器端职责，计划在后续版本提供。
* 动图支持仍计划在后续版本提供。


---

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