Gitea Docker中网页文件上传数量如何限制？

Question

在使用 Gitea Docker 部署时，如何限制网页端单次提交中允许上传的文件数量？默认配置下，Gitea 仅限制单个文件大小（通过 `MAX_FILE_SIZE`），但未提供直接参数控制上传文件总数。这可能导致用户批量上传大量小文件，影响系统性能或存储管理。常见问题出现在私有部署环境中，如企业代码托管平台，需对 Web 界面的 Git 上传行为进行更细粒度管控。尽管可通过 Nginx 层做请求体大小限制，但这无法精确限制文件“数量”。因此，亟需了解是否可通过 Gitea 的配置项（如 `app.ini`）、Docker 启动参数或反向代理策略实现文件上传数量的限制，或是否有版本更新支持此类功能。

Answer 1

1. 背景与问题定义

在使用 Gitea Docker 部署时，如何限制网页端单次提交中允许上传的文件数量？这是许多企业级私有代码托管平台面临的实际挑战。Gitea 默认通过 MAX_FILE_SIZE 参数控制单个文件大小，但并未提供直接配置项来限制一次 Web 提交中可添加的文件总数。这可能导致用户通过 Web 界面批量上传成百上千个小文件（如日志、临时资源等），造成数据库压力增大、Git 仓库膨胀或前端响应延迟。

尽管可通过 Nginx 设置 client_max_body_size 来间接控制请求体总大小，但这无法精确识别“文件数量”，也无法区分是单个大文件还是多个小文件。因此，需探索更细粒度的管控机制。

2. Gitea 原生配置能力分析

Gitea 的核心配置文件为 app.ini，其常见与上传相关的参数如下表所示：

配置项	作用说明	是否支持文件数限制
MAX_FILE_SIZE	单个文件最大允许大小（MB）	否
ATTACHMENT_MAX_SIZE	附件上传大小限制	否
HTTP_TIMEOUT	HTTP 请求超时时间	无关
DISABLE_GIT_HOOKS	禁用 Git 钩子脚本	潜在扩展点

从官方文档和源码层面来看，截至 Gitea v1.21.x 版本，尚无内置参数支持限制单次提交的文件数量。这意味着必须依赖外部策略或自定义开发实现该功能。

3. 反向代理层的可行性方案（Nginx + Lua）

虽然 Nginx 本身不能解析 multipart/form-data 中的文件个数，但结合 OpenResty（Nginx + Lua 模块）可实现对上传内容的深度解析。以下是一个基于 Lua 的示例逻辑：

location /repo/owner/submit {
    access_by_lua_block {
        local content_type = ngx.req.get_headers()["content-type"]
        if content_type and string.find(content_type, "multipart/form-data") then
            ngx.req.read_body()
            local form, err = require("mime.multipart").new(ngx.req.get_body_data(), content_type)
            if not form then return end

            local file_count = 0
            for part in form:parts() do
                if part.filename then
                    file_count = file_count + 1
                    if file_count > 50 then  -- 限制最多50个文件
                        ngx.status = 413
                        ngx.say("Too many files in one commit")
                        ngx.exit(ngx.HTTP_REQUEST_ENTITY_TOO_LARGE)
                    end
                end
            end
        end
    }
    proxy_pass http://gitea_backend;
}

此方法可在反向代理层拦截并解析表单数据，实现对文件数量的硬性限制。适用于高安全要求的企业环境。

4. 客户端与前端层面的辅助控制

另一种思路是在 Gitea 前端界面中加入 JavaScript 校验逻辑。例如，在 Web 编辑器提交前监听页面事件：

• 监听文件选择控件（<input type="file" multiple>）的 change 事件
• 获取 event.target.files.length
• 若超过预设阈值（如 30 个），弹出警告并阻止提交

示例代码片段：

document.getElementById('fileInput').addEventListener('change', function(e) {
    const maxFiles = 30;
    if (e.target.files.length > maxFiles) {
        alert(`单次提交最多允许上传 ${maxFiles} 个文件`);
        e.target.value = ''; // 清空选择
    }
});

注意：此方式仅作提示性防护，可被绕过，适合搭配后端校验使用。

5. 自定义 Git Hook 或中间服务拦截

由于 Web 提交最终会触发 Git 操作，可在仓库级别设置 pre-receive hook，分析 incoming commit 中的文件变更数量：

#!/bin/bash
# pre-receive hook 示例
while read oldrev newrev refname; do
    added_files=$(git diff --name-only $oldrev $newrev | wc -l)
    if [ $added_files -gt 100 ]; then
        echo "Error: Commit adds too many files ($added_files). Maximum allowed: 100."
        exit 1
    fi
done

该方案需配合 Gitea 的 custom_hooks 目录部署，并确保所有仓库启用。可通过自动化脚本批量注入钩子。

6. 架构级建议与未来展望

为实现长期可维护的文件数量管控，推荐采用分层防御策略：

1. 前端提示：提升用户体验，提前告知限制
2. 反向代理拦截：使用 OpenResty 实现精准文件计数
3. Git Hook 校验：防止 CLI 提交绕过 Web 限制
4. 审计日志：记录异常提交行为，用于后续分析

Mermaid 流程图展示整体控制流程：

graph TD
    A[用户发起Web提交] --> B{前端JS校验文件数}
    B -- 超限 --> C[阻止提交并提示]
    B -- 正常 --> D[发送至Nginx/OpenResty]
    D --> E{Lua解析multipart}
    E -- 文件数>阈值 --> F[返回413]
    E -- 合法 --> G[转发至Gitea]
    G --> H[Gitea处理提交]
    H --> I{pre-receive hook检查}
    I -- 新增文件过多 --> J[拒绝push]
    I -- 正常 --> K[提交成功]

目前 Gitea 社区尚未将“文件数量限制”纳入核心功能 roadmap，但可通过插件化或 fork 修改前端控制器逻辑来增强。建议关注 GitHub 上相关 issue（如 #19382）的进展。