docs: annotate Foundry source and deployment lifecycle in Chinese [skip ci]

This commit is contained in:
2026-11-16 17:52:11 +08:00
parent 30829eeb86
commit 1090591503
123 changed files with 1279 additions and 3 deletions
+20
View File
@@ -1,3 +1,4 @@
// 预览派生与进程内缓存:只缓存不可变图片字节,权限必须由调用方每次读取前另行检查。
package platform
import (
@@ -17,23 +18,30 @@ import (
"golang.org/x/image/draw"
)
// assetPreviewResult 只包含编码字节和 MIME,可与原图共用只读切片,禁止调用者原地修改。
type assetPreviewResult struct {
data []byte
mime string
}
// assetPreviewEntry 存储在 LRU 链表中,key 同时作为 map 索引,便于常数时间淘汰。
type assetPreviewEntry struct {
key string
value assetPreviewResult
}
// 缓存最多保留 32 MiB/128 项编码结果,互斥锁只覆盖索引操作,不覆盖解码缩放。
var previewMemory = struct {
sync.Mutex
entries map[string]*list.Element
order *list.List
bytes int
}{entries: make(map[string]*list.Element), order: list.New()}
// previewSlots 将所有预览完整解码限制为单并发,避免多个大图同时分配像素内存。
var previewSlots = make(chan struct{}, 1)
// previewWidth 仅接受原图或固定 1024 预览,不允许任意宽度组合造成无界缓存键。
func previewWidth(variant, width string) (int, error) {
if variant == "" && width == "" {
return 0, nil
@@ -46,6 +54,7 @@ func previewWidth(variant, width string) (int, error) {
// Cache only immutable bytes, after the caller checks current asset permission.
// Bound both decoded concurrency and retained encoded data.
// cachedAssetPreview 用原图摘要与宽度做键,命中即提升 LRU;等待执行槽可随请求取消。
func cachedAssetPreview(ctx context.Context, encoded []byte, mime string, width int) (assetPreviewResult, error) {
key := fmt.Sprintf("%x:%d", sha256.Sum256(encoded), width)
previewMemory.Lock()
@@ -75,6 +84,7 @@ func cachedAssetPreview(ctx context.Context, encoded []byte, mime string, width
if err != nil {
return result, err
}
// 单项过大仍可响应,但不留在缓存;其余按字节和项数双预算淘汰末尾最久未用项。
if len(result.data) > 8<<20 {
return result, nil
}
@@ -95,6 +105,7 @@ func cachedAssetPreview(ctx context.Context, encoded []byte, mime string, width
return result, nil
}
// makeAssetPreview 保留 GIF 动画和足够小的原图,其余应用 EXIF 后等比例缩至最长边预算。
func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResult, error) {
original := assetPreviewResult{encoded, mime}
// Keep animation intact. Original bytes remain the canonical AI/download input.
@@ -134,6 +145,7 @@ func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResul
draw.CatmullRom.Scale(resized, resized.Bounds(), source, source.Bounds(), draw.Src, nil)
var output bytes.Buffer
outputMime := "image/png"
// 不透明预览编码 JPEG 以减体积,透明预览保留 PNG;原图字节始终不被覆盖。
if resized.Opaque() {
err = jpeg.Encode(&output, resized, &jpeg.Options{Quality: 82})
outputMime = "image/jpeg"
@@ -143,6 +155,7 @@ func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResul
if err != nil {
return original, err
}
// 无需修正方向且重编码没有变小时直接用原图,避免更大派生文件。
if output.Len() >= len(encoded) && orientation == 1 {
return original, nil
}
@@ -151,6 +164,7 @@ func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResul
// JPEG EXIF orientation is applied to previews instead of silently rotating a
// phone photograph after its EXIF metadata is removed by the image encoder.
// jpegOrientation 仅解析 JPEG APP1 中 TIFF 的 Orientation,逐层检查长度,异常/缺省均返回正常方向一。
func jpegOrientation(data []byte) int {
if len(data) < 4 || data[0] != 0xff || data[1] != 0xd8 {
return 1
@@ -206,11 +220,13 @@ func jpegOrientation(data []byte) int {
return 1
}
// orientedAsset 是只读坐标适配视图,不复制像素;5–8 方向旋转后宽高交换。
type orientedAsset struct {
image.Image
orientation int
}
// Bounds 报告纠正方向后的零起点矩形,供缩放器计算目标比例。
func (im orientedAsset) Bounds() image.Rectangle {
b := im.Image.Bounds()
if im.orientation >= 5 {
@@ -218,7 +234,11 @@ func (im orientedAsset) Bounds() image.Rectangle {
}
return image.Rect(0, 0, b.Dx(), b.Dy())
}
// ColorModel 继承原图颜色模型,实际像素读取交由 At 做反向坐标映射。
func (im orientedAsset) ColorModel() color.Model { return im.Image.ColorModel() }
// At 将显示坐标映回原图,再补 Bounds.Min,覆盖 EXIF 八种旋转/镜像组合。
func (im orientedAsset) At(x, y int) color.Color {
b := im.Image.Bounds()
w, h := b.Dx(), b.Dy()