- libraryagent:0700 目录内 0600 unix socket + SO_PEERCRED 同 uid, 固定 binary/归档/日志/项目/写入者声明,请求只能选范围与作业号 - API:POST/GET /api/v1/library/captures(入队 library.capture + 读队列状态) - worker:library.capture handler 走 socket;启动先 recover;不挂 Docker socket、 不持有来源凭据 - web:整库版本页显示真实作业状态并可发起封存(未接线/无权限给出原因) - scripts/library-agent-install.sh:构建、安装 systemd user 服务并读回权限
This commit is contained in:
@@ -0,0 +1,106 @@
|
||||
package httpapi
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"regexp"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"knowledge-governance/internal/jobs"
|
||||
)
|
||||
|
||||
// 页面发起封存:只投递一个作业,真正的停机/导出/恢复发生在主机侧 agent。
|
||||
// 这里没有任何 Docker 访问,也没有来源凭据 —— 调用方只能选择范围与作业号。
|
||||
const libraryCaptureJobType = "library.capture"
|
||||
|
||||
var libraryCaptureJobPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{1,64}$`)
|
||||
|
||||
type libraryCaptureRequest struct {
|
||||
Scope string `json:"scope"`
|
||||
Job string `json:"job"`
|
||||
}
|
||||
|
||||
func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config) {
|
||||
if config.LibraryAgentSocket == "" {
|
||||
writeJSON(w, http.StatusServiceUnavailable, map[string]any{
|
||||
"code": "library_capture_unwired",
|
||||
"reason": "未接线:主机侧封存 agent 没有挂载,页面无法发起封存",
|
||||
})
|
||||
return
|
||||
}
|
||||
var request libraryCaptureRequest
|
||||
if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4096)).Decode(&request); err != nil {
|
||||
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"})
|
||||
return
|
||||
}
|
||||
if request.Scope != "internal" && request.Scope != "external" {
|
||||
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "scope must be internal or external"})
|
||||
return
|
||||
}
|
||||
// The job id is the idempotency key handed to the agent: repeating the same
|
||||
// scope+job returns the already sealed version instead of sealing twice.
|
||||
captureJob := strings.TrimSpace(request.Job)
|
||||
if captureJob == "" {
|
||||
captureJob = "lib-" + request.Scope + "-" + time.Now().UTC().Format("20060102T150405")
|
||||
}
|
||||
if !libraryCaptureJobPattern.MatchString(captureJob) {
|
||||
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid job id"})
|
||||
return
|
||||
}
|
||||
requestedBy := ""
|
||||
if identity, ok := sessionFrom(r.Context()); ok {
|
||||
requestedBy = identity.Username
|
||||
}
|
||||
payload, err := json.Marshal(map[string]string{
|
||||
"scope": request.Scope, "capture_job": captureJob, "requested_by": requestedBy,
|
||||
})
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot build capture job"})
|
||||
return
|
||||
}
|
||||
now := time.Now().UTC()
|
||||
job, err := config.Store.Enqueue(r.Context(), jobs.EnqueueRequest{
|
||||
ID: fmt.Sprintf("library-capture-%s-%d", request.Scope, now.UnixNano()),
|
||||
Type: libraryCaptureJobType,
|
||||
Payload: payload,
|
||||
AvailableAt: now,
|
||||
MaxAttempts: 2,
|
||||
IdempotencyKey: "library.capture:" + captureJob,
|
||||
}, now)
|
||||
if err != nil || job == nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot enqueue capture job"})
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusAccepted, map[string]any{
|
||||
"job_id": job.ID, "capture_job": captureJob, "scope": request.Scope, "state": job.State,
|
||||
})
|
||||
}
|
||||
|
||||
// libraryCaptureJobs lists recent capture jobs so the page can show real state
|
||||
// instead of an optimistic spinner. It reads the queue, not the archive.
|
||||
func libraryCaptureJobs(w http.ResponseWriter, r *http.Request, config Config) {
|
||||
queue, err := config.Store.List(r.Context(), 200)
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read capture jobs"})
|
||||
return
|
||||
}
|
||||
views := make([]map[string]any, 0, 20)
|
||||
for _, job := range queue {
|
||||
if job.Type != libraryCaptureJobType || len(views) >= 20 {
|
||||
continue
|
||||
}
|
||||
var payload struct {
|
||||
Scope string `json:"scope"`
|
||||
CaptureJob string `json:"capture_job"`
|
||||
RequestedBy string `json:"requested_by"`
|
||||
}
|
||||
_ = json.Unmarshal(job.Payload, &payload)
|
||||
views = append(views, map[string]any{"job_id": job.ID, "capture_job": payload.CaptureJob,
|
||||
"scope": payload.Scope, "state": job.State, "attempt": job.Attempt,
|
||||
"last_error": job.LastError, "requested_by": payload.RequestedBy,
|
||||
"created_at": job.CreatedAt, "updated_at": job.UpdatedAt})
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]any{"available": true, "jobs": views})
|
||||
}
|
||||
@@ -0,0 +1,111 @@
|
||||
package httpapi
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"knowledge-governance/internal/jobs"
|
||||
)
|
||||
|
||||
func captureRequest(body string) *http.Request {
|
||||
request := httptest.NewRequest(http.MethodPost, "/api/v1/library/captures", strings.NewReader(body))
|
||||
request.Header.Set("Content-Type", "application/json")
|
||||
return request
|
||||
}
|
||||
|
||||
// An unwired agent must refuse clearly instead of queueing a job nobody can run.
|
||||
func TestLibraryCaptureRefusedWhenAgentUnwired(t *testing.T) {
|
||||
store := &fakeJobStore{}
|
||||
recorder := httptest.NewRecorder()
|
||||
libraryCaptureEnqueue(recorder, captureRequest(`{"scope":"internal"}`), Config{Store: store})
|
||||
if recorder.Code != http.StatusServiceUnavailable {
|
||||
t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
|
||||
}
|
||||
var body map[string]any
|
||||
if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if body["code"] != "library_capture_unwired" || body["reason"] == "" {
|
||||
t.Fatalf("unexpected body %v", body)
|
||||
}
|
||||
if store.enqueued.Type != "" {
|
||||
t.Fatal("unwired agent still enqueued a job")
|
||||
}
|
||||
}
|
||||
|
||||
func TestLibraryCaptureEnqueuesFixedJobShape(t *testing.T) {
|
||||
store := &fakeJobStore{enqueueEchoRequestedID: true}
|
||||
recorder := httptest.NewRecorder()
|
||||
libraryCaptureEnqueue(recorder, captureRequest(`{"scope":"external","job":"lib-external-review"}`),
|
||||
Config{Store: store, LibraryAgentSocket: "/run/library-agent/agent.sock"})
|
||||
if recorder.Code != http.StatusAccepted {
|
||||
t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
|
||||
}
|
||||
enqueued := store.enqueued
|
||||
if enqueued.Type != libraryCaptureJobType {
|
||||
t.Fatalf("job type %q", enqueued.Type)
|
||||
}
|
||||
if enqueued.IdempotencyKey != "library.capture:lib-external-review" {
|
||||
t.Fatalf("idempotency key %q", enqueued.IdempotencyKey)
|
||||
}
|
||||
var payload map[string]string
|
||||
if err := json.Unmarshal(enqueued.Payload, &payload); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if payload["scope"] != "external" || payload["capture_job"] != "lib-external-review" {
|
||||
t.Fatalf("payload %v", payload)
|
||||
}
|
||||
var body map[string]any
|
||||
if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if body["capture_job"] != "lib-external-review" || body["scope"] != "external" {
|
||||
t.Fatalf("response %v", body)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLibraryCaptureRejectsInvalidRequest(t *testing.T) {
|
||||
for _, body := range []string{
|
||||
`{"scope":"production"}`,
|
||||
`{"scope":"internal","job":"bad job; rm -rf /"}`,
|
||||
`not json`,
|
||||
} {
|
||||
store := &fakeJobStore{}
|
||||
recorder := httptest.NewRecorder()
|
||||
libraryCaptureEnqueue(recorder, captureRequest(body), Config{Store: store, LibraryAgentSocket: "/tmp/agent.sock"})
|
||||
if recorder.Code != http.StatusBadRequest {
|
||||
t.Fatalf("body %q status=%d", body, recorder.Code)
|
||||
}
|
||||
if store.enqueued.Type != "" {
|
||||
t.Fatalf("invalid request %q still enqueued", body)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestLibraryCaptureJobsListsOnlyCaptureJobs(t *testing.T) {
|
||||
store := &fakeJobStore{listResult: []jobs.Job{
|
||||
{ID: "a", Type: libraryCaptureJobType, State: "completed",
|
||||
Payload: json.RawMessage(`{"scope":"internal","capture_job":"lib-internal-1","requested_by":"yaozhanghao"}`),
|
||||
CreatedAt: time.Date(2026, 10, 28, 3, 0, 0, 0, time.UTC)},
|
||||
{ID: "b", Type: "artifact.fetch", State: "completed"},
|
||||
}}
|
||||
recorder := httptest.NewRecorder()
|
||||
libraryCaptureJobs(recorder, httptest.NewRequest(http.MethodGet, "/api/v1/library/captures", nil), Config{Store: store})
|
||||
if recorder.Code != http.StatusOK {
|
||||
t.Fatalf("status=%d", recorder.Code)
|
||||
}
|
||||
var body struct {
|
||||
Available bool `json:"available"`
|
||||
Jobs []map[string]any `json:"jobs"`
|
||||
}
|
||||
if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !body.Available || len(body.Jobs) != 1 || body.Jobs[0]["capture_job"] != "lib-internal-1" {
|
||||
t.Fatalf("unexpected body %+v", body)
|
||||
}
|
||||
}
|
||||
@@ -58,14 +58,20 @@ type librarySnapshotList struct {
|
||||
UnreferencedBytes int64 `json:"unreferenced_bytes"`
|
||||
ManifestFileBytes int64 `json:"manifest_file_bytes"`
|
||||
ManifestAllocatedBytes int64 `json:"manifest_allocated_bytes"`
|
||||
// 页面必须能说清"封存由谁执行",不能让人以为页面上有个没实现的按钮。
|
||||
CaptureNote string `json:"capture_note"`
|
||||
// 页面必须能说清"封存由谁执行";能不能从这里发起,取决于主机侧 agent 是否接线。
|
||||
CaptureNote string `json:"capture_note"`
|
||||
CaptureAvailable bool `json:"capture_available"`
|
||||
CaptureReason string `json:"capture_reason,omitempty"`
|
||||
}
|
||||
|
||||
const libraryCaptureNote = "封存由运维命令 scripts/library-capture.sh capture -scope internal|external 在目标主机执行(停写入者→导出→恢复)。页面只读展示已封存的完整版本:它通过了数据完整性检查(身份、双向正文覆盖、生成问题、资源与摘要),这已满足封版所需的完整性口径;授权与生产同步仍是独立步骤。"
|
||||
|
||||
func librarySnapshotsList(w http.ResponseWriter, r *http.Request, config Config) {
|
||||
view, err := readLibrarySnapshots(config.LibraryArchiveRoot)
|
||||
view.CaptureAvailable = config.LibraryAgentSocket != ""
|
||||
if !view.CaptureAvailable {
|
||||
view.CaptureReason = "未接线:主机侧封存 agent 没有挂载,页面只能查看已封存版本"
|
||||
}
|
||||
if err != nil {
|
||||
writeJSON(w, http.StatusServiceUnavailable, librarySnapshotList{Available: false,
|
||||
Reason: "归档不可读:" + err.Error(), Snapshots: []librarySnapshotView{}, CaptureNote: libraryCaptureNote})
|
||||
@@ -110,6 +116,7 @@ func librarySnapshotDetail(w http.ResponseWriter, r *http.Request, config Config
|
||||
|
||||
func readLibrarySnapshots(root string) (librarySnapshotList, error) {
|
||||
view := librarySnapshotList{Snapshots: []librarySnapshotView{}, CaptureNote: libraryCaptureNote}
|
||||
_ = root
|
||||
if root == "" {
|
||||
view.Reason = "未接线:LIBRARY_ARCHIVE_ROOT 未配置,本平台没有整库归档可读"
|
||||
return view, nil
|
||||
|
||||
@@ -130,7 +130,9 @@ type Config struct {
|
||||
VersionHistory VersionHistoryStore
|
||||
VersionHistoryRepo string
|
||||
// LibraryArchiveRoot 是整库封存产物的只读归档根;留空即未接线(页面降级)。
|
||||
LibraryArchiveRoot string
|
||||
LibraryArchiveRoot string
|
||||
// LibraryAgentSocket 是主机侧封存 agent 的 unix socket;留空即页面不能发起封存。
|
||||
LibraryAgentSocket string
|
||||
BackupSchedule BackupScheduleStore
|
||||
BackupHost BackupHost
|
||||
BackupRuns *BackupRunTracker
|
||||
@@ -396,6 +398,13 @@ func NewHandler(config Config) (http.Handler, error) {
|
||||
mux.HandleFunc("GET /api/v1/library/snapshots/{id}", func(w http.ResponseWriter, r *http.Request) {
|
||||
librarySnapshotDetail(w, r, config)
|
||||
})
|
||||
// 页面发起封存:只投递作业(主机侧 agent 执行),并回读作业真实状态。
|
||||
mux.HandleFunc("POST /api/v1/library/captures", func(w http.ResponseWriter, r *http.Request) {
|
||||
libraryCaptureEnqueue(w, r, config)
|
||||
})
|
||||
mux.HandleFunc("GET /api/v1/library/captures", func(w http.ResponseWriter, r *http.Request) {
|
||||
libraryCaptureJobs(w, r, config)
|
||||
})
|
||||
// 全部 main 提交时间线(读本库缓存,不直接打 Gitea)
|
||||
mux.HandleFunc("GET /api/v1/version-history", func(w http.ResponseWriter, r *http.Request) {
|
||||
versionHistoryList(w, r, config)
|
||||
|
||||
Reference in New Issue
Block a user