diff --git a/docs/admin-deployment.md b/docs/admin-deployment.md index 3bf849a..50f6e64 100644 --- a/docs/admin-deployment.md +++ b/docs/admin-deployment.md @@ -49,6 +49,8 @@ project 表只新增 moderation_reason 和 repo_write_status,来源标识、 全部写入端按项目编码取得同一 MySQL 命名锁,使用固定连接取得、持有和释放,支持内部重入。锁连接池每应用最多 8 个连接,另有普通业务连接池,需要预留数据库容量。远端请求期间不持有数据库长事务;写入前持久化状态,结果不明时重启后仍阻断写入。 +普通文件上传的写入状态依次为 `IDLE → WRITING → IDLE`,最终恢复空闲后记录“仓库写入完成”日志。Gitea 已提交但响应丢失、状态回写失败等未知结果进入 `REVIEW`;即使 main 已有最新提交,发布仍会被阻断。上传提交前或发布前的 Gitea 读取失败应恢复 `IDLE`,异常传递保留远端结果确定性,避免把只读失败误标为未知写入。历史 `REVIEW` 仍需按实际操作结果人工核对恢复。 + 上线前确认目标 Gitea 已开启迁移、HTTP Git、LFS,技术账号具有组织仓库写权限。GitHub 预检优先读取 API;受限时严格核对公开网页身份、可见性和默认分支,无法确认时失败。网页回退拿不到的简介、许可证可能为空,需要管理员检查原仓库文件。 失败迁移重试需要技术账号及 Token 具有目标私有仓库读取、迁移创建及删除权限。后台迁移时在 Gitea 仓库描述中写入任务归属标识;不要手工修改该标识。它仅用于失败仓库清理核验,不改变社区项目的名称和描述。 @@ -72,6 +74,14 @@ project 表只新增 moderation_reason 和 repo_write_status,来源标识、 逻辑删除、撤回和下架不会物理删除 Gitea 仓库或 OSS 对象;已公开 OSS 链接沿用现有生命周期。 +### 普通项目人工核对后的写入恢复 + +普通项目同时使用数据库 `repo_write_status` 和各写入进程内的待核对集合。只把数据库改为 `IDLE`,已有内存标记会在下一次提交或发布时重新写回 `REVIEW`;仅重启进程也无法解除数据库中保留的 `REVIEW` 或 `WRITING`。启动后首次请求若发现数据库未空闲,又会建立本进程的待核对标记。 + +先按项目编码核对 Gitea 仓库身份、预期文件和提交历史,确认上次远端写入已结束。普通项目当前没有在线恢复接口;核对完成后停止社区 API、管理 API 及仍在运行的导入写入进程,再仅针对已核实的项目恢复数据库为 `IDLE`,最后启动上述服务。恢复后刷新目录并由管理员明确发布,恢复本身不更改发布状态或远端文件。多个进程需全部处理,避免仍持有旧标记的进程再次写回 `REVIEW`。 + +写入拦截日志同时记录 `persistedWriteStatus` 和 `memoryUncertain`。`persistedWriteStatus=IDLE memoryUncertain=true` 表示数据库已恢复、本进程仍保留待核对标记;`memoryUncertain=false` 且数据库非 `IDLE` 表示本次由持久化状态阻断。这两种拦截均发生在本次业务写入和发布 SHA 校验之前,不表示本次请求已调用 Gitea 写入。 + ## 验证 ```bash diff --git a/vibemake-adminapi/src/test/java/com/linkerbot/vibemake/adminapi/AdminWorkflowTest.java b/vibemake-adminapi/src/test/java/com/linkerbot/vibemake/adminapi/AdminWorkflowTest.java index 111c1ce..8aee8bc 100644 --- a/vibemake-adminapi/src/test/java/com/linkerbot/vibemake/adminapi/AdminWorkflowTest.java +++ b/vibemake-adminapi/src/test/java/com/linkerbot/vibemake/adminapi/AdminWorkflowTest.java @@ -17,6 +17,8 @@ import com.linkerbot.vibemake.service.oss.OssObjectStore; import com.linkerbot.vibemake.service.support.*; import org.junit.jupiter.api.*; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.autoconfigure.web.servlet.*; import org.springframework.boot.test.context.*; @@ -167,6 +169,89 @@ class AdminWorkflowTest { .asText(); } + private MockHttpServletRequestBuilder uploadRequest(String code, String sha) { + return signed(multipart("/admin-api/projects/" + code + "/uploads/commit") + .file(new MockMultipartFile("files", "sample.txt", "text/plain", "hello".getBytes())) + .param("expectedCommitSha", sha) + .param("message", "测试上传") + .param("paths", "models/sample.txt")); + } + + private String writeState(String code) { + return jdbc.queryForObject( + "SELECT repo_write_status FROM project WHERE project_code=?", String.class, code); + } + + @ParameterizedTest + @ValueSource(strings = {"upload", "publication"}) + void readFailureBeforeUploadOrPublicationDoesNotBlockLaterWrites(String operation) throws Exception { + String code = createProject(); + String initial = request(signed(get("/admin-api/projects/" + code + "/tree")), 200) + .path("data").path("commitSha").asText(); + gitea.timeoutNextHead = true; + MockHttpServletRequestBuilder first = operation.equals("upload") + ? uploadRequest(code, initial) + : signed(body(put("/admin-api/projects/" + code + "/publication"), + Map.of("commitSha", initial))); + JsonNode failure = request(first, 504); + assertThat(failure.path("code").asText()).isEqualTo("REMOTE_RESULT_UNKNOWN"); + assertThat(failure.path("data").path("projectCode").asText()).isEqualTo(code); + assertThat(writeState(code)).isEqualTo("IDLE"); + assertThat(request(signed(get("/admin-api/projects/" + code + "/tree")), 200) + .path("data").path("commitSha").asText()).isEqualTo(initial); + String current = operation.equals("upload") + ? request(uploadRequest(code, initial), 200).path("data").path("commitSha").asText() + : initial; + assertThat(writeState(code)).isEqualTo("IDLE"); + request(signed(body(put("/admin-api/projects/" + code + "/publication"), + Map.of("commitSha", current))), 200); + assertThat(writeState(code)).isEqualTo("IDLE"); + assertThat(projectService.published(code).getPublishedCommitSha()).isEqualTo(current); + } + + @Test + void uploadedCommitWithLostResponseStillBlocksPublicationAtLatestSha() throws Exception { + String code = createProject(); + String initial = request(signed(get("/admin-api/projects/" + code + "/tree")), 200) + .path("data").path("commitSha").asText(); + gitea.timeoutNextCommit = true; + JsonNode failure = request(uploadRequest(code, initial), 504); + assertThat(failure.path("code").asText()).isEqualTo("REMOTE_RESULT_UNKNOWN"); + assertThat(failure.path("data").path("projectCode").asText()).isEqualTo(code); + assertThat(writeState(code)).isEqualTo("REVIEW"); + String current = request(signed(get("/admin-api/projects/" + code + "/tree")), 200) + .path("data").path("commitSha").asText(); + assertThat(current).isNotEqualTo(initial); + assertThat(request(signed(get("/admin-api/projects/" + code + "/files") + .param("path", "models/sample.txt")), 200) + .path("data").path("content").asText()).isEqualTo("hello"); + JsonNode blocked = request(signed(body( + put("/admin-api/projects/" + code + "/publication"), Map.of("commitSha", current))), 409); + assertThat(blocked.path("code").asText()).isEqualTo("REMOTE_RESULT_UNKNOWN"); + assertThat(writeState(code)).isEqualTo("REVIEW"); + assertThat(projects.selectOne(new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper() + .eq(Project::getProjectCode, code)).getPublishedCommitSha()).isNull(); + + // 只改数据库不能清除当前进程的待核对标记,下一次写入会重新持久化 REVIEW。 + jdbc.update("UPDATE project SET repo_write_status='IDLE' WHERE project_code=?", code); + assertThat(writeState(code)).isEqualTo("IDLE"); + JsonNode blockedAgain = request(signed(body( + put("/admin-api/projects/" + code + "/publication"), Map.of("commitSha", current))), 409); + assertThat(blockedAgain.path("code").asText()).isEqualTo("REMOTE_RESULT_UNKNOWN"); + assertThat(writeState(code)).isEqualTo("REVIEW"); + + // 模拟核对远端结果后持锁恢复,同时清除数据库和本进程标记。 + locks.serial(code, () -> { + locks.confirmKnownResult(code); + return null; + }); + assertThat(writeState(code)).isEqualTo("IDLE"); + request(signed(body(put("/admin-api/projects/" + code + "/publication"), + Map.of("commitSha", current))), 200); + assertThat(writeState(code)).isEqualTo("IDLE"); + assertThat(projectService.published(code).getPublishedCommitSha()).isEqualTo(current); + } + private JsonNode createImport() throws Exception { return request( signed( diff --git a/vibemake-adminapi/src/test/java/com/linkerbot/vibemake/adminapi/FakeGiteaClient.java b/vibemake-adminapi/src/test/java/com/linkerbot/vibemake/adminapi/FakeGiteaClient.java index 8bfd3f8..78f814f 100644 --- a/vibemake-adminapi/src/test/java/com/linkerbot/vibemake/adminapi/FakeGiteaClient.java +++ b/vibemake-adminapi/src/test/java/com/linkerbot/vibemake/adminapi/FakeGiteaClient.java @@ -30,6 +30,7 @@ final class FakeGiteaClient implements GiteaClient { final Map migrationDescriptions = new HashMap<>(); private final Set mainReady = new HashSet<>(); boolean timeoutNextCommit; + boolean timeoutNextHead; boolean timeoutNextCreate; boolean failNextCreate; @@ -46,6 +47,7 @@ final class FakeGiteaClient implements GiteaClient { deletionRejected = false; mainConflict = false; timeoutNextCommit = false; + timeoutNextHead = false; timeoutNextCreate = false; failNextCreate = false; } @@ -100,6 +102,10 @@ final class FakeGiteaClient implements GiteaClient { @Override public synchronized String head(Repository repository) { + if (timeoutNextHead) { + timeoutNextHead = false; + throw new GiteaFailure(504, "REMOTE_RESULT_UNKNOWN", "读取分支超时", false); + } return repo(repository).head; } diff --git a/vibemake-service/src/main/java/com/linkerbot/vibemake/service/gitea/GiteaFailure.java b/vibemake-service/src/main/java/com/linkerbot/vibemake/service/gitea/GiteaFailure.java index 4201dee..0968747 100644 --- a/vibemake-service/src/main/java/com/linkerbot/vibemake/service/gitea/GiteaFailure.java +++ b/vibemake-service/src/main/java/com/linkerbot/vibemake/service/gitea/GiteaFailure.java @@ -6,7 +6,11 @@ public class GiteaFailure extends BusinessException { private final boolean uncertain; public GiteaFailure(int status, String code, String message, boolean uncertain) { - super(status, code, message); + this(status, code, message, uncertain, null); + } + + public GiteaFailure(int status, String code, String message, boolean uncertain, Object details) { + super(status, code, message, details); this.uncertain = uncertain; } diff --git a/vibemake-service/src/main/java/com/linkerbot/vibemake/service/impl/ProjectServiceImpl.java b/vibemake-service/src/main/java/com/linkerbot/vibemake/service/impl/ProjectServiceImpl.java index 1e78216..c917548 100644 --- a/vibemake-service/src/main/java/com/linkerbot/vibemake/service/impl/ProjectServiceImpl.java +++ b/vibemake-service/src/main/java/com/linkerbot/vibemake/service/impl/ProjectServiceImpl.java @@ -536,11 +536,15 @@ public class ProjectServiceImpl implements ProjectService { code, error.code(), error.uncertain()); - throw new BusinessException( + // 保留远端结果确定性,避免读取失败被外层写入保护误判为未知写入。 + GiteaFailure failure = new GiteaFailure( error.status(), error.code(), error.getMessage(), + error.uncertain(), Map.of("projectCode", code)); + failure.initCause(error); + throw failure; } }); } diff --git a/vibemake-service/src/main/java/com/linkerbot/vibemake/service/support/ProjectLocks.java b/vibemake-service/src/main/java/com/linkerbot/vibemake/service/support/ProjectLocks.java index c9a9219..b42dae0 100644 --- a/vibemake-service/src/main/java/com/linkerbot/vibemake/service/support/ProjectLocks.java +++ b/vibemake-service/src/main/java/com/linkerbot/vibemake/service/support/ProjectLocks.java @@ -83,8 +83,12 @@ public class ProjectLocks { () -> { if (writing.get().contains(code)) return action.get(); Project guard = guard(code); - if (uncertain.contains(code) + boolean memoryUncertain = uncertain.contains(code); + if (memoryUncertain || guard != null && !"IDLE".equals(guard.getRepoWriteStatus())) { + log.warn( + "仓库写入被阻止 projectCode={} persistedWriteStatus={} memoryUncertain={}", + code, guard == null ? null : guard.getRepoWriteStatus(), memoryUncertain); markUncertain(code); throw blocked(); } @@ -101,7 +105,10 @@ public class ProjectLocks { 503, "PROJECT_LOCK_UNAVAILABLE", "持锁连接已断开,请核对操作结果"); } } - if (!uncertain.contains(code)) state(code, "IDLE"); + if (!uncertain.contains(code)) { + state(code, "IDLE"); + log.info("仓库写入完成 projectCode={} writeStatus=IDLE", code); + } return result; } catch (RuntimeException error) { boolean unknown =