Compare commits

..

5 Commits

Author SHA1 Message Date
d-robotics
03dd5ffbfd merge: complete DEPLOY-002 Kubernetes Helm delivery 2026-09-03 13:07:19 +08:00
d-robotics
5100d98e3c deploy: add Kubernetes Helm delivery 2026-09-03 12:21:54 +08:00
d-robotics
d727d0a118 merge: complete DEPLOY-001 production images 2026-09-03 11:01:58 +08:00
d-robotics
72dc248bbc build: add production process images 2026-09-02 21:16:33 +08:00
d-robotics
a1eae16fb1 merge: complete DEMO-016 batch async upload 2026-09-02 20:43:26 +08:00
44 changed files with 2312 additions and 14 deletions

21
.dockerignore Normal file
View File

@ -0,0 +1,21 @@
# Keep credentials, local state, caches, and developer artifacts out of every image context.
.env
.env.*
!.env.example
.git
.github
.idea
.vscode
.DS_Store
.mypy_cache
.pytest_cache
.ruff_cache
.venv
__pycache__
*.py[cod]
*.sqlite*
dist
storage
tests
docs
docker-compose.dev.yml

View File

@ -4,6 +4,8 @@ LOG_LEVEL=INFO
API_HOST=0.0.0.0
API_PORT=8000
API_PREFIX=/api/v1
# Optional outside source checkouts; production image fixes this to /app/apps/admin-web.
# ADMIN_WEB_ROOT=/absolute/path/to/apps/admin-web
DATABASE_URL=mysql+pymysql://ekp:change-me@localhost:2881/ekp
DATABASE_POOL_SIZE=10

View File

@ -1,4 +1,4 @@
.PHONY: help install run run-mcp run-worker format format-check lint typecheck test test-unit test-integration migration-check eval live-acceptance up down
.PHONY: help install run run-mcp run-worker images images-print images-push deploy deploy-lint deploy-render format format-check lint typecheck test test-unit test-integration migration-check eval live-acceptance up down
UV_CACHE_DIR ?= /tmp/ekp-uv-cache
export UV_CACHE_DIR
@ -9,6 +9,12 @@ help:
@echo " run Start the development API"
@echo " run-mcp Start the authenticated MCP gateway"
@echo " run-worker Start the ingestion worker and recovery scheduler"
@echo " images Build production images for the current builder"
@echo " images-print Render the multi-architecture image build plan"
@echo " images-push Build and push amd64/arm64 production images"
@echo " deploy Install or upgrade Kubernetes with VALUES=<file>"
@echo " deploy-lint Validate Helm values and templates"
@echo " deploy-render Render non-secret Kubernetes manifests"
@echo " format Format code"
@echo " format-check Check formatting without modifying files"
@echo " lint Run linters"
@ -30,6 +36,20 @@ run-mcp:
uv run ekp-mcp
run-worker:
uv run ekp-worker
images:
docker buildx bake -f deploy/docker/docker-bake.hcl
images-print:
docker buildx bake -f deploy/docker/docker-bake.hcl --print
images-push:
docker buildx bake -f deploy/docker/docker-bake.hcl --push
deploy:
./scripts/deploy.sh "$(VALUES)"
deploy-lint:
@test -n "$(VALUES)" || (echo "VALUES must point to an environment values file" >&2; exit 2)
helm lint deploy/helm/knowledge-platform --values "$(VALUES)"
deploy-render:
@test -n "$(VALUES)" || (echo "VALUES must point to an environment values file" >&2; exit 2)
helm template "$${RELEASE:-knowledge-platform}" deploy/helm/knowledge-platform --namespace "$${NAMESPACE:-knowledge-platform}" --values "$(VALUES)"
format:
uv run ruff format .
format-check:

View File

@ -76,6 +76,11 @@ The Demo Admin Console is available at `http://localhost:8000/admin` and contain
only document upload, document management, and Search Lab pages. See
`docs/development/ADMIN_CONSOLE.md` for the operation and scope boundaries.
DEPLOY-001 provides locked, non-root `api`, `mcp`, and `worker` production image targets with an
amd64/arm64 Buildx Bake plan. DEPLOY-002 adds the Kubernetes/Helm Chart, runtime Secret references,
serialized Migration, Ingress/TLS and the `make deploy VALUES=<file>` entrypoint. See
`docs/development/CONTAINER_IMAGES.md` and `docs/development/KUBERNETES_DEPLOYMENT.md`.
Run the development checks with:
```bash

View File

@ -37,12 +37,13 @@ def create_app(
application.state.settings = resolved_settings
application.state.api_services = api_services
application.include_router(router, prefix=resolved_settings.api_prefix)
admin_web_root = (resolved_settings.admin_web_root or ADMIN_WEB_ROOT).resolve()
# The Demo console is a deliberately thin, same-origin client. It contains
# no business logic and calls only the versioned public REST API.
application.mount(
"/admin/assets",
StaticFiles(directory=ADMIN_WEB_ROOT / "assets"),
StaticFiles(directory=admin_web_root / "assets"),
name="admin-assets",
)
@ -52,7 +53,7 @@ def create_app(
@application.get("/admin/search", include_in_schema=False)
async def admin_console() -> FileResponse:
"""Serve the three-page Demo Admin Console shell."""
return FileResponse(ADMIN_WEB_ROOT / "index.html")
return FileResponse(admin_web_root / "index.html")
@application.get("/healthz", response_model=HealthResponse, tags=["system"])
async def health() -> HealthResponse:

61
deploy/docker/Dockerfile Normal file
View File

@ -0,0 +1,61 @@
# syntax=docker/dockerfile:1.7
# One locked runtime produces three independently deployable process images.
ARG PYTHON_IMAGE=python:3.12.14-slim-bookworm@sha256:782412e85d0f0984994c290652577d4018aff08145c85b262bb63dc0c7522254
ARG UV_IMAGE=ghcr.io/astral-sh/uv:0.12.5@sha256:e85be844203885286c60ffad8a858d48afb6c5a5c237ca0e67f12e74b8f174b1
FROM ${UV_IMAGE} AS uv-bin
FROM ${PYTHON_IMAGE} AS runtime
ENV PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
UV_COMPILE_BYTECODE=1 \
UV_LINK_MODE=copy \
VIRTUAL_ENV=/app/.venv \
PATH=/app/.venv/bin:${PATH} \
HOME=/tmp/ekp \
XDG_CACHE_HOME=/tmp/ekp/cache \
APP_ENV=production \
API_HOST=0.0.0.0 \
MCP_HOST=0.0.0.0 \
ADMIN_WEB_ROOT=/app/apps/admin-web
WORKDIR /app
COPY --from=uv-bin /uv /uvx /usr/local/bin/
COPY pyproject.toml uv.lock README.md alembic.ini ./
COPY apps ./apps
COPY packages ./packages
COPY migrations ./migrations
# --frozen prevents lock changes; --no-dev and --no-editable keep the runtime
# independent from source-tree import hooks while retaining migration sources.
RUN uv sync --frozen --no-dev --no-editable \
&& test -f /app/apps/admin-web/index.html \
&& groupadd --gid 10001 ekp \
&& useradd --uid 10001 --gid 10001 --no-create-home --shell /usr/sbin/nologin ekp \
&& mkdir -p /tmp/ekp/cache \
&& chown -R 10001:10001 /tmp/ekp \
&& rm -rf /root/.cache/uv
USER 10001:10001
FROM runtime AS api
EXPOSE 8000
# This endpoint is intentionally credential-free and suitable for container liveness.
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=2)"]
CMD ["uvicorn", "ekp_api.main:app", "--host", "0.0.0.0", "--port", "8000", "--no-access-log"]
FROM runtime AS mcp
EXPOSE 8766
# MCP requests require authentication, so the image-level check only verifies PID 1.
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
CMD ["python", "-c", "import os; os.kill(1, 0)"]
CMD ["ekp-mcp"]
FROM runtime AS worker
# Worker health is process-level here; durable Job recovery is validated by the service tests.
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
CMD ["python", "-c", "import os; os.kill(1, 0)"]
CMD ["ekp-worker"]

View File

@ -0,0 +1,36 @@
# Reproducible target names consumed by local and CI buildx invocations.
variable "IMAGE_REGISTRY" {
default = "knowledge-platform"
}
variable "IMAGE_TAG" {
default = "dev"
}
group "default" {
targets = ["api", "mcp", "worker"]
}
target "common" {
context = "."
dockerfile = "deploy/docker/Dockerfile"
platforms = ["linux/amd64", "linux/arm64"]
}
target "api" {
inherits = ["common"]
target = "api"
tags = ["${IMAGE_REGISTRY}/enterprise-knowledge-api:${IMAGE_TAG}"]
}
target "mcp" {
inherits = ["common"]
target = "mcp"
tags = ["${IMAGE_REGISTRY}/enterprise-knowledge-mcp:${IMAGE_TAG}"]
}
target "worker" {
inherits = ["common"]
target = "worker"
tags = ["${IMAGE_REGISTRY}/enterprise-knowledge-worker:${IMAGE_TAG}"]
}

View File

@ -0,0 +1,50 @@
# Copy this file outside the repository for one environment. It contains only
# non-sensitive settings and Kubernetes Secret references; never add values for
# DATABASE_URL, RABBITMQ_URL, provider keys, passwords or MCP_AUTH_TOKEN here.
existingSecret: knowledge-platform-runtime
images:
api:
repository: registry.example.internal/knowledge/enterprise-knowledge-api
tag: "0.1.0"
digest: ""
mcp:
repository: registry.example.internal/knowledge/enterprise-knowledge-mcp
tag: "0.1.0"
digest: ""
worker:
repository: registry.example.internal/knowledge/enterprise-knowledge-worker
tag: "0.1.0"
digest: ""
ingress:
enabled: true
className: nginx
api:
host: knowledge.example.internal
tlsSecretName: knowledge-platform-api-tls
mcp:
host: mcp.example.internal
tlsSecretName: knowledge-platform-mcp-tls
config:
objectStorage:
endpoint: https://s3.example.internal
bucket: knowledge-platform
vectorStore:
uri: oceanbase.example.internal:2881
user: knowledge-platform
database: knowledge_platform
mcp:
publicUrl: https://mcp.example.internal/mcp
issuerUrl: https://mcp.example.internal
allowedHosts:
- mcp.example.internal
allowedOrigins:
- https://mcp.example.internal
# External RabbitMQ is the production default. If this local dependency is
# explicitly enabled for a demo cluster, create its Secret before deployment.
rabbitmq:
enabled: false
existingSecret: knowledge-platform-rabbitmq

View File

@ -0,0 +1,15 @@
apiVersion: v2
name: knowledge-platform
description: Enterprise Knowledge Platform public-knowledge deployment
type: application
version: 0.1.0
appVersion: "0.1.0"
# This local dependency is disabled by default. Production deployments should
# use an externally managed RabbitMQ service with an independently owned data
# lifecycle; the subchart exists only for explicit development/demo use.
dependencies:
- name: rabbitmq
version: 0.1.0
repository: file://charts/rabbitmq
condition: rabbitmq.enabled

View File

@ -0,0 +1,6 @@
apiVersion: v2
name: rabbitmq
description: Minimal single-node RabbitMQ dependency for local demo clusters only
type: application
version: 0.1.0
appVersion: "4.1.4"

View File

@ -0,0 +1,11 @@
{{- define "rabbitmq.fullname" -}}
{{- printf "%s-rabbitmq" .Release.Name | trunc 63 | trimSuffix "-" -}}
{{- end -}}
{{- define "rabbitmq.image" -}}
{{- if .Values.image.digest -}}
{{- printf "%s@%s" .Values.image.repository .Values.image.digest -}}
{{- else -}}
{{- printf "%s:%s" .Values.image.repository .Values.image.tag -}}
{{- end -}}
{{- end -}}

View File

@ -0,0 +1,16 @@
apiVersion: v1
kind: Service
metadata:
name: {{ include "rabbitmq.fullname" . }}
labels:
app.kubernetes.io/name: rabbitmq
app.kubernetes.io/instance: {{ .Release.Name }}
spec:
clusterIP: None
ports:
- name: amqp
port: {{ .Values.service.port }}
targetPort: amqp
selector:
app.kubernetes.io/name: rabbitmq
app.kubernetes.io/instance: {{ .Release.Name }}

View File

@ -0,0 +1,8 @@
apiVersion: v1
kind: ServiceAccount
metadata:
name: {{ include "rabbitmq.fullname" . }}
labels:
app.kubernetes.io/name: rabbitmq
app.kubernetes.io/instance: {{ .Release.Name }}
automountServiceAccountToken: false

View File

@ -0,0 +1,109 @@
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: {{ include "rabbitmq.fullname" . }}
labels:
app.kubernetes.io/name: rabbitmq
app.kubernetes.io/instance: {{ .Release.Name }}
spec:
serviceName: {{ include "rabbitmq.fullname" . }}
replicas: 1
selector:
matchLabels:
app.kubernetes.io/name: rabbitmq
app.kubernetes.io/instance: {{ .Release.Name }}
template:
metadata:
labels:
app.kubernetes.io/name: rabbitmq
app.kubernetes.io/instance: {{ .Release.Name }}
spec:
serviceAccountName: {{ include "rabbitmq.fullname" . }}
automountServiceAccountToken: false
securityContext:
runAsNonRoot: true
runAsUser: 999
runAsGroup: 999
fsGroup: 999
seccompProfile:
type: RuntimeDefault
containers:
- name: rabbitmq
image: {{ include "rabbitmq.image" . | quote }}
imagePullPolicy: {{ .Values.image.pullPolicy }}
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop: ["ALL"]
ports:
- name: amqp
containerPort: 5672
env:
- name: RABBITMQ_DEFAULT_USER
valueFrom:
secretKeyRef:
name: {{ .Values.existingSecret }}
key: {{ .Values.secretKeys.username }}
- name: RABBITMQ_DEFAULT_PASS
valueFrom:
secretKeyRef:
name: {{ .Values.existingSecret }}
key: {{ .Values.secretKeys.password }}
- name: RABBITMQ_ERLANG_COOKIE
valueFrom:
secretKeyRef:
name: {{ .Values.existingSecret }}
key: {{ .Values.secretKeys.erlangCookie }}
startupProbe:
exec:
command: ["rabbitmq-diagnostics", "-q", "ping"]
periodSeconds: 5
failureThreshold: 24
readinessProbe:
exec:
command: ["rabbitmq-diagnostics", "-q", "check_running"]
periodSeconds: 10
timeoutSeconds: 5
failureThreshold: 3
livenessProbe:
exec:
command: ["rabbitmq-diagnostics", "-q", "ping"]
periodSeconds: 20
timeoutSeconds: 5
failureThreshold: 3
resources:
{{- toYaml .Values.resources | nindent 12 }}
volumeMounts:
- name: data
mountPath: /var/lib/rabbitmq
- name: config
mountPath: /etc/rabbitmq/conf.d
- name: log
mountPath: /var/log/rabbitmq
- name: tmp
mountPath: /tmp
volumes:
- name: config
emptyDir: {}
- name: log
emptyDir: {}
- name: tmp
emptyDir: {}
{{- if not .Values.persistence.enabled }}
- name: data
emptyDir: {}
{{- end }}
{{- if .Values.persistence.enabled }}
volumeClaimTemplates:
- metadata:
name: data
spec:
accessModes: [{{ .Values.persistence.accessMode | quote }}]
{{- if .Values.persistence.storageClass }}
storageClassName: {{ .Values.persistence.storageClass | quote }}
{{- end }}
resources:
requests:
storage: {{ .Values.persistence.size }}
{{- end }}

View File

@ -0,0 +1,69 @@
{
"$schema": "https://json-schema.org/draft-07/schema#",
"type": "object",
"additionalProperties": false,
"required": ["enabled", "existingSecret", "secretKeys", "image", "service", "persistence", "resources"],
"properties": {
"global": {"type": "object"},
"enabled": {"type": "boolean"},
"existingSecret": {"type": "string", "minLength": 1},
"secretKeys": {
"type": "object",
"additionalProperties": false,
"required": ["username", "password", "erlangCookie"],
"properties": {
"username": {"type": "string", "minLength": 1},
"password": {"type": "string", "minLength": 1},
"erlangCookie": {"type": "string", "minLength": 1}
}
},
"image": {
"type": "object",
"additionalProperties": false,
"required": ["repository", "tag", "digest", "pullPolicy"],
"properties": {
"repository": {"type": "string", "minLength": 1},
"tag": {"type": "string", "minLength": 1, "not": {"enum": ["latest"]}},
"digest": {"type": "string", "pattern": "^$|^sha256:[a-f0-9]{64}$"},
"pullPolicy": {"enum": ["Always", "IfNotPresent", "Never"]}
}
},
"service": {
"type": "object",
"additionalProperties": false,
"required": ["port"],
"properties": {"port": {"type": "integer", "minimum": 1, "maximum": 65535}}
},
"persistence": {
"type": "object",
"additionalProperties": false,
"required": ["enabled", "storageClass", "accessMode", "size"],
"properties": {
"enabled": {"type": "boolean"},
"storageClass": {"type": "string"},
"accessMode": {"enum": ["ReadWriteOnce", "ReadWriteMany"]},
"size": {"type": "string", "minLength": 2}
}
},
"resources": {
"type": "object",
"additionalProperties": false,
"required": ["requests", "limits"],
"properties": {
"requests": {"$ref": "#/definitions/resourcePair"},
"limits": {"$ref": "#/definitions/resourcePair"}
}
}
},
"definitions": {
"resourcePair": {
"type": "object",
"additionalProperties": false,
"required": ["cpu", "memory"],
"properties": {
"cpu": {"type": ["string", "number"]},
"memory": {"type": "string", "minLength": 2}
}
}
}
}

View File

@ -0,0 +1,25 @@
enabled: false
existingSecret: knowledge-platform-rabbitmq
secretKeys:
username: username
password: password
erlangCookie: erlang-cookie
image:
repository: rabbitmq
tag: 4.1.4-alpine
digest: sha256:b736d649308e1b3e1a116c3f36986b605ee3d03e88f10166be2900083d2e63f2
pullPolicy: IfNotPresent
service:
port: 5672
persistence:
enabled: true
storageClass: ""
accessMode: ReadWriteOnce
size: 8Gi
resources:
requests:
cpu: 250m
memory: 512Mi
limits:
cpu: "1"
memory: 1Gi

View File

@ -0,0 +1,12 @@
Enterprise Knowledge Platform {{ .Chart.AppVersion }} is managed by Helm release {{ .Release.Name }}.
Runtime credentials are read only from Secret {{ .Values.existingSecret }}.
{{- if .Values.ingress.enabled }}
Admin/API: https://{{ .Values.ingress.api.host }}{{ .Values.ingress.api.path }}
MCP: https://{{ .Values.ingress.mcp.host }}{{ .Values.ingress.mcp.path }}
{{- else }}
Ingress is disabled. Enable it in the environment values file before remote use.
{{- end }}
Inspect rollout state without printing environment variables:
kubectl -n {{ .Release.Namespace }} get deploy,job,pod

View File

@ -0,0 +1,106 @@
{{/* Stable resource name helpers keep every workload under one release identity. */}}
{{- define "knowledge-platform.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
{{- end -}}
{{- define "knowledge-platform.fullname" -}}
{{- if .Values.fullnameOverride -}}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
{{- else -}}
{{- $name := include "knowledge-platform.name" . -}}
{{- if contains $name .Release.Name -}}
{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
{{- else -}}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
{{- end -}}
{{- end -}}
{{- end -}}
{{- define "knowledge-platform.labels" -}}
helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | quote }}
app.kubernetes.io/name: {{ include "knowledge-platform.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end -}}
{{- define "knowledge-platform.selectorLabels" -}}
app.kubernetes.io/name: {{ include "knowledge-platform.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end -}}
{{- define "knowledge-platform.serviceAccountName" -}}
{{- if .Values.serviceAccount.create -}}
{{- default (include "knowledge-platform.fullname" .) .Values.serviceAccount.name -}}
{{- else -}}
{{- required "serviceAccount.name is required when serviceAccount.create=false" .Values.serviceAccount.name -}}
{{- end -}}
{{- end -}}
{{/* A supplied digest takes precedence over the immutable release tag. */}}
{{- define "knowledge-platform.image" -}}
{{- if .digest -}}
{{- printf "%s@%s" .repository .digest -}}
{{- else -}}
{{- printf "%s:%s" .repository .tag -}}
{{- end -}}
{{- end -}}
{{- define "knowledge-platform.configMapName" -}}
{{- printf "%s-runtime" (include "knowledge-platform.fullname" .) -}}
{{- end -}}
{{/* Cross-field rules complement values.schema.json's structural checks. */}}
{{- define "knowledge-platform.validateValues" -}}
{{- if lt (float64 .Values.config.ingestion.retryBackoffMaxSeconds) (float64 .Values.config.ingestion.retryBackoffSeconds) -}}
{{- fail "config.ingestion.retryBackoffMaxSeconds must be >= retryBackoffSeconds" -}}
{{- end -}}
{{- if lt (float64 .Values.config.ingestion.batchMaxTotalBytes) (float64 .Values.config.ingestion.maxUploadBytes) -}}
{{- fail "config.ingestion.batchMaxTotalBytes must be >= maxUploadBytes" -}}
{{- end -}}
{{- if ge (float64 .Values.config.chunking.overlapTokens) (float64 .Values.config.chunking.maxTokens) -}}
{{- fail "config.chunking.overlapTokens must be < maxTokens" -}}
{{- end -}}
{{- if gt (float64 .Values.config.retrieval.searchTopK) (float64 .Values.config.retrieval.denseTopN) -}}
{{- fail "config.retrieval.searchTopK must be <= denseTopN" -}}
{{- end -}}
{{- end -}}
{{- define "knowledge-platform.podSecurityContext" -}}
runAsNonRoot: true
runAsUser: 10001
runAsGroup: 10001
fsGroup: 10001
fsGroupChangePolicy: OnRootMismatch
seccompProfile:
type: RuntimeDefault
{{- end -}}
{{- define "knowledge-platform.containerSecurityContext" -}}
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
runAsNonRoot: true
runAsUser: 10001
runAsGroup: 10001
capabilities:
drop:
- ALL
{{- end -}}
{{- define "knowledge-platform.envFrom" -}}
- configMapRef:
name: {{ include "knowledge-platform.configMapName" . }}
- secretRef:
name: {{ .Values.existingSecret }}
{{- end -}}
{{- define "knowledge-platform.tmpVolume" -}}
- name: tmp
emptyDir:
sizeLimit: 1Gi
{{- end -}}
{{- define "knowledge-platform.tmpMount" -}}
- name: tmp
mountPath: /tmp
{{- end -}}

View File

@ -0,0 +1,75 @@
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "knowledge-platform.fullname" . }}-api
labels:
{{- include "knowledge-platform.labels" . | nindent 4 }}
app.kubernetes.io/component: api
spec:
replicas: {{ .Values.api.replicaCount }}
minReadySeconds: 5
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 0
maxSurge: 1
selector:
matchLabels:
{{- include "knowledge-platform.selectorLabels" . | nindent 6 }}
app.kubernetes.io/component: api
template:
metadata:
labels:
{{- include "knowledge-platform.selectorLabels" . | nindent 8 }}
app.kubernetes.io/component: api
{{- with .Values.podLabels }}
{{- toYaml . | nindent 8 }}
{{- end }}
annotations:
checksum/runtime-config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
checksum/runtime-secret-reference: {{ .Values.existingSecret | sha256sum }}
{{- with .Values.podAnnotations }}
{{- toYaml . | nindent 8 }}
{{- end }}
spec:
serviceAccountName: {{ include "knowledge-platform.serviceAccountName" . }}
automountServiceAccountToken: false
securityContext:
{{- include "knowledge-platform.podSecurityContext" . | nindent 8 }}
{{- with .Values.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: api
image: {{ include "knowledge-platform.image" .Values.images.api | quote }}
imagePullPolicy: {{ .Values.images.api.pullPolicy }}
securityContext:
{{- include "knowledge-platform.containerSecurityContext" . | nindent 12 }}
ports:
- name: http
containerPort: 8000
protocol: TCP
envFrom:
{{- include "knowledge-platform.envFrom" . | nindent 12 }}
startupProbe:
httpGet:
path: /healthz
port: http
{{- toYaml .Values.api.probes.startup | nindent 12 }}
readinessProbe:
httpGet:
path: /healthz
port: http
{{- toYaml .Values.api.probes.readiness | nindent 12 }}
livenessProbe:
httpGet:
path: /healthz
port: http
{{- toYaml .Values.api.probes.liveness | nindent 12 }}
resources:
{{- toYaml .Values.api.resources | nindent 12 }}
volumeMounts:
{{- include "knowledge-platform.tmpMount" . | nindent 12 }}
volumes:
{{- include "knowledge-platform.tmpVolume" . | nindent 8 }}

View File

@ -0,0 +1,17 @@
apiVersion: v1
kind: Service
metadata:
name: {{ include "knowledge-platform.fullname" . }}-api
labels:
{{- include "knowledge-platform.labels" . | nindent 4 }}
app.kubernetes.io/component: api
spec:
type: {{ .Values.api.service.type }}
ports:
- name: http
port: {{ .Values.api.service.port }}
targetPort: http
protocol: TCP
selector:
{{- include "knowledge-platform.selectorLabels" . | nindent 4 }}
app.kubernetes.io/component: api

View File

@ -0,0 +1,66 @@
{{- include "knowledge-platform.validateValues" . }}
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ include "knowledge-platform.configMapName" . }}
labels:
{{- include "knowledge-platform.labels" . | nindent 4 }}
data:
# Only the explicitly enumerated non-sensitive settings are rendered here.
APP_ENV: "production"
APP_NAME: {{ .Values.config.appName | quote }}
LOG_LEVEL: {{ .Values.config.logLevel | quote }}
API_HOST: "0.0.0.0"
API_PORT: "8000"
API_PREFIX: "/api/v1"
DATABASE_POOL_SIZE: {{ .Values.config.database.poolSize | quote }}
DATABASE_MAX_OVERFLOW: {{ .Values.config.database.maxOverflow | quote }}
DATABASE_POOL_RECYCLE_SECONDS: {{ .Values.config.database.poolRecycleSeconds | quote }}
DATABASE_POOL_TIMEOUT_SECONDS: {{ .Values.config.database.poolTimeoutSeconds | quote }}
DATABASE_CONNECT_TIMEOUT_SECONDS: {{ .Values.config.database.connectTimeoutSeconds | quote }}
INGESTION_MAX_ATTEMPTS: {{ .Values.config.ingestion.maxAttempts | quote }}
INGESTION_RETRY_BACKOFF_SECONDS: {{ .Values.config.ingestion.retryBackoffSeconds | quote }}
INGESTION_RETRY_BACKOFF_MAX_SECONDS: {{ .Values.config.ingestion.retryBackoffMaxSeconds | quote }}
INGESTION_WORKER_LEASE_SECONDS: {{ .Values.config.ingestion.workerLeaseSeconds | quote }}
INGESTION_RECOVERY_INTERVAL_SECONDS: {{ .Values.config.ingestion.recoveryIntervalSeconds | quote }}
BATCH_MAX_FILES: {{ .Values.config.ingestion.batchMaxFiles | quote }}
BATCH_MAX_TOTAL_BYTES: {{ printf "%.0f" .Values.config.ingestion.batchMaxTotalBytes | quote }}
MAX_UPLOAD_BYTES: {{ printf "%.0f" .Values.config.ingestion.maxUploadBytes | quote }}
OBJECT_STORAGE_PROVIDER: {{ .Values.config.objectStorage.provider | quote }}
BOS_ENDPOINT: {{ .Values.config.objectStorage.endpoint | quote }}
BOS_BUCKET: {{ .Values.config.objectStorage.bucket | quote }}
BOS_KEY_PREFIX: {{ .Values.config.objectStorage.keyPrefix | quote }}
BOS_TIMEOUT_SECONDS: {{ .Values.config.objectStorage.timeoutSeconds | quote }}
CHUNK_MAX_TOKENS: {{ .Values.config.chunking.maxTokens | quote }}
CHUNK_OVERLAP_TOKENS: {{ .Values.config.chunking.overlapTokens | quote }}
CHUNK_MAX_CHARACTERS: {{ .Values.config.chunking.maxCharacters | quote }}
EMBEDDING_PROVIDER: {{ .Values.config.embedding.provider | quote }}
EMBEDDING_MODEL: {{ .Values.config.embedding.model | quote }}
EMBEDDING_ENDPOINT: {{ .Values.config.embedding.endpoint | quote }}
EMBEDDING_TIMEOUT_SECONDS: {{ .Values.config.embedding.timeoutSeconds | quote }}
VECTOR_STORE_PROVIDER: {{ .Values.config.vectorStore.provider | quote }}
OCEANBASE_VECTOR_URI: {{ .Values.config.vectorStore.uri | quote }}
OCEANBASE_VECTOR_USER: {{ .Values.config.vectorStore.user | quote }}
OCEANBASE_VECTOR_DATABASE: {{ .Values.config.vectorStore.database | quote }}
OCEANBASE_VECTOR_TABLE: {{ .Values.config.vectorStore.table | quote }}
OCEANBASE_VECTOR_INDEX: {{ .Values.config.vectorStore.index | quote }}
OCEANBASE_VECTOR_BATCH_SIZE: {{ .Values.config.vectorStore.batchSize | quote }}
OCEANBASE_VECTOR_TIMEOUT_SECONDS: {{ .Values.config.vectorStore.timeoutSeconds | quote }}
INDEX_PROFILE_ID: {{ .Values.config.retrieval.indexProfileId | quote }}
DENSE_TOP_N: {{ .Values.config.retrieval.denseTopN | quote }}
SEARCH_TOP_K: {{ .Values.config.retrieval.searchTopK | quote }}
RERANKER_PROVIDER: {{ .Values.config.reranker.provider | quote }}
RERANKER_MODEL: {{ .Values.config.reranker.model | quote }}
RERANKER_ENDPOINT: {{ .Values.config.reranker.endpoint | quote }}
RERANKER_TIMEOUT_SECONDS: {{ .Values.config.reranker.timeoutSeconds | quote }}
MCP_HOST: "0.0.0.0"
MCP_PORT: "8766"
MCP_PATH: "/mcp"
MCP_PUBLIC_URL: {{ .Values.config.mcp.publicUrl | quote }}
MCP_ISSUER_URL: {{ .Values.config.mcp.issuerUrl | quote }}
MCP_CLIENT_ID: {{ .Values.config.mcp.clientId | quote }}
MCP_SERVICE_IDENTITY: {{ .Values.config.mcp.serviceIdentity | quote }}
MCP_REQUIRED_SCOPE: {{ .Values.config.mcp.requiredScope | quote }}
MCP_ALLOWED_HOSTS: {{ .Values.config.mcp.allowedHosts | toJson | quote }}
MCP_ALLOWED_ORIGINS: {{ .Values.config.mcp.allowedOrigins | toJson | quote }}
MCP_MAX_REQUEST_BODY_BYTES: {{ printf "%.0f" .Values.config.mcp.maxRequestBodyBytes | quote }}

View File

@ -0,0 +1,42 @@
{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: {{ include "knowledge-platform.fullname" . }}
labels:
{{- include "knowledge-platform.labels" . | nindent 4 }}
{{- with .Values.ingress.annotations }}
annotations:
{{- toYaml . | nindent 4 }}
{{- end }}
spec:
ingressClassName: {{ .Values.ingress.className }}
tls:
- hosts:
- {{ .Values.ingress.api.host | quote }}
secretName: {{ .Values.ingress.api.tlsSecretName }}
- hosts:
- {{ .Values.ingress.mcp.host | quote }}
secretName: {{ .Values.ingress.mcp.tlsSecretName }}
rules:
- host: {{ .Values.ingress.api.host | quote }}
http:
paths:
- path: {{ .Values.ingress.api.path }}
pathType: Prefix
backend:
service:
name: {{ include "knowledge-platform.fullname" . }}-api
port:
number: {{ .Values.api.service.port }}
- host: {{ .Values.ingress.mcp.host | quote }}
http:
paths:
- path: {{ .Values.ingress.mcp.path }}
pathType: Prefix
backend:
service:
name: {{ include "knowledge-platform.fullname" . }}-mcp
port:
number: {{ .Values.mcp.service.port }}
{{- end }}

View File

@ -0,0 +1,72 @@
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "knowledge-platform.fullname" . }}-mcp
labels:
{{- include "knowledge-platform.labels" . | nindent 4 }}
app.kubernetes.io/component: mcp
spec:
replicas: {{ .Values.mcp.replicaCount }}
minReadySeconds: 5
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 0
maxSurge: 1
selector:
matchLabels:
{{- include "knowledge-platform.selectorLabels" . | nindent 6 }}
app.kubernetes.io/component: mcp
template:
metadata:
labels:
{{- include "knowledge-platform.selectorLabels" . | nindent 8 }}
app.kubernetes.io/component: mcp
{{- with .Values.podLabels }}
{{- toYaml . | nindent 8 }}
{{- end }}
annotations:
checksum/runtime-config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
checksum/runtime-secret-reference: {{ .Values.existingSecret | sha256sum }}
{{- with .Values.podAnnotations }}
{{- toYaml . | nindent 8 }}
{{- end }}
spec:
serviceAccountName: {{ include "knowledge-platform.serviceAccountName" . }}
automountServiceAccountToken: false
securityContext:
{{- include "knowledge-platform.podSecurityContext" . | nindent 8 }}
{{- with .Values.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: mcp
image: {{ include "knowledge-platform.image" .Values.images.mcp | quote }}
imagePullPolicy: {{ .Values.images.mcp.pullPolicy }}
securityContext:
{{- include "knowledge-platform.containerSecurityContext" . | nindent 12 }}
ports:
- name: mcp
containerPort: 8766
protocol: TCP
envFrom:
{{- include "knowledge-platform.envFrom" . | nindent 12 }}
startupProbe:
tcpSocket:
port: mcp
{{- toYaml .Values.mcp.probes.startup | nindent 12 }}
readinessProbe:
tcpSocket:
port: mcp
{{- toYaml .Values.mcp.probes.readiness | nindent 12 }}
livenessProbe:
tcpSocket:
port: mcp
{{- toYaml .Values.mcp.probes.liveness | nindent 12 }}
resources:
{{- toYaml .Values.mcp.resources | nindent 12 }}
volumeMounts:
{{- include "knowledge-platform.tmpMount" . | nindent 12 }}
volumes:
{{- include "knowledge-platform.tmpVolume" . | nindent 8 }}

View File

@ -0,0 +1,17 @@
apiVersion: v1
kind: Service
metadata:
name: {{ include "knowledge-platform.fullname" . }}-mcp
labels:
{{- include "knowledge-platform.labels" . | nindent 4 }}
app.kubernetes.io/component: mcp
spec:
type: {{ .Values.mcp.service.type }}
ports:
- name: mcp
port: {{ .Values.mcp.service.port }}
targetPort: mcp
protocol: TCP
selector:
{{- include "knowledge-platform.selectorLabels" . | nindent 4 }}
app.kubernetes.io/component: mcp

View File

@ -0,0 +1,59 @@
{{- if .Values.migration.enabled }}
apiVersion: batch/v1
kind: Job
metadata:
name: {{ include "knowledge-platform.fullname" . }}-migration
labels:
{{- include "knowledge-platform.labels" . | nindent 4 }}
app.kubernetes.io/component: migration
annotations:
# Helm waits for pre-install/pre-upgrade hooks. A failed migration blocks
# the application rollout, and the previous Job remains until the next run.
helm.sh/hook: pre-install,pre-upgrade
helm.sh/hook-weight: "-10"
helm.sh/hook-delete-policy: before-hook-creation
spec:
backoffLimit: {{ .Values.migration.backoffLimit }}
activeDeadlineSeconds: {{ .Values.migration.activeDeadlineSeconds }}
ttlSecondsAfterFinished: {{ .Values.migration.ttlSecondsAfterFinished }}
template:
metadata:
labels:
{{- include "knowledge-platform.selectorLabels" . | nindent 8 }}
app.kubernetes.io/component: migration
spec:
restartPolicy: Never
# Pre-install hooks run before the release ServiceAccount exists. The
# namespace default account is used with token mounting disabled; the
# migration needs no Kubernetes API permissions.
serviceAccountName: default
automountServiceAccountToken: false
securityContext:
{{- include "knowledge-platform.podSecurityContext" . | nindent 8 }}
{{- with .Values.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: migration
image: {{ include "knowledge-platform.image" .Values.images.api | quote }}
imagePullPolicy: {{ .Values.images.api.pullPolicy }}
command: ["alembic"]
args: ["upgrade", "head"]
securityContext:
{{- include "knowledge-platform.containerSecurityContext" . | nindent 12 }}
env:
- name: APP_ENV
value: production
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: {{ .Values.existingSecret }}
key: DATABASE_URL
resources:
{{- toYaml .Values.migration.resources | nindent 12 }}
volumeMounts:
{{- include "knowledge-platform.tmpMount" . | nindent 12 }}
volumes:
{{- include "knowledge-platform.tmpVolume" . | nindent 8 }}
{{- end }}

View File

@ -0,0 +1,71 @@
{{- if .Values.scheduler.enabled }}
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "knowledge-platform.fullname" . }}-scheduler
labels:
{{- include "knowledge-platform.labels" . | nindent 4 }}
app.kubernetes.io/component: scheduler
spec:
# A single Celery Beat owns periodic durable-Job recovery. Recreate prevents
# two schedulers from overlapping during upgrades.
replicas: 1
strategy:
type: Recreate
selector:
matchLabels:
{{- include "knowledge-platform.selectorLabels" . | nindent 6 }}
app.kubernetes.io/component: scheduler
template:
metadata:
labels:
{{- include "knowledge-platform.selectorLabels" . | nindent 8 }}
app.kubernetes.io/component: scheduler
{{- with .Values.podLabels }}
{{- toYaml . | nindent 8 }}
{{- end }}
annotations:
checksum/runtime-config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
checksum/runtime-secret-reference: {{ .Values.existingSecret | sha256sum }}
{{- with .Values.podAnnotations }}
{{- toYaml . | nindent 8 }}
{{- end }}
spec:
serviceAccountName: {{ include "knowledge-platform.serviceAccountName" . }}
automountServiceAccountToken: false
securityContext:
{{- include "knowledge-platform.podSecurityContext" . | nindent 8 }}
{{- with .Values.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: scheduler
image: {{ include "knowledge-platform.image" .Values.images.worker | quote }}
imagePullPolicy: {{ .Values.images.worker.pullPolicy }}
workingDir: /tmp
command: ["celery"]
args:
- --app=ekp_api.worker:celery_app
- beat
- --loglevel=INFO
- --schedule=/tmp/celerybeat-schedule
securityContext:
{{- include "knowledge-platform.containerSecurityContext" . | nindent 12 }}
envFrom:
{{- include "knowledge-platform.envFrom" . | nindent 12 }}
startupProbe:
exec:
command: ["python", "-c", "import os; os.kill(1, 0)"]
{{- toYaml .Values.scheduler.probes.startup | nindent 12 }}
livenessProbe:
exec:
command: ["python", "-c", "import os; os.kill(1, 0)"]
{{- toYaml .Values.scheduler.probes.liveness | nindent 12 }}
resources:
{{- toYaml .Values.scheduler.resources | nindent 12 }}
volumeMounts:
{{- include "knowledge-platform.tmpMount" . | nindent 12 }}
volumes:
{{- include "knowledge-platform.tmpVolume" . | nindent 8 }}
{{- end }}

View File

@ -0,0 +1,13 @@
{{- if .Values.serviceAccount.create }}
apiVersion: v1
kind: ServiceAccount
metadata:
name: {{ include "knowledge-platform.serviceAccountName" . }}
labels:
{{- include "knowledge-platform.labels" . | nindent 4 }}
{{- with .Values.serviceAccount.annotations }}
annotations:
{{- toYaml . | nindent 4 }}
{{- end }}
automountServiceAccountToken: false
{{- end }}

View File

@ -0,0 +1,17 @@
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ include "knowledge-platform.fullname" . }}-preflight-references
labels:
{{- include "knowledge-platform.labels" . | nindent 4 }}
annotations:
# The Make preflight renders this test hook to discover only resource
# names. It never renders or reads Secret data.
helm.sh/hook: test
data:
runtimeSecret: {{ .Values.existingSecret | quote }}
ingressEnabled: {{ .Values.ingress.enabled | quote }}
apiTlsSecret: {{ .Values.ingress.api.tlsSecretName | quote }}
mcpTlsSecret: {{ .Values.ingress.mcp.tlsSecretName | quote }}
rabbitmqEnabled: {{ .Values.rabbitmq.enabled | quote }}
rabbitmqSecret: {{ .Values.rabbitmq.existingSecret | quote }}

View File

@ -0,0 +1,71 @@
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "knowledge-platform.fullname" . }}-worker
labels:
{{- include "knowledge-platform.labels" . | nindent 4 }}
app.kubernetes.io/component: worker
spec:
replicas: {{ .Values.worker.replicaCount }}
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 1
maxSurge: 1
selector:
matchLabels:
{{- include "knowledge-platform.selectorLabels" . | nindent 6 }}
app.kubernetes.io/component: worker
template:
metadata:
labels:
{{- include "knowledge-platform.selectorLabels" . | nindent 8 }}
app.kubernetes.io/component: worker
{{- with .Values.podLabels }}
{{- toYaml . | nindent 8 }}
{{- end }}
annotations:
checksum/runtime-config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
checksum/runtime-secret-reference: {{ .Values.existingSecret | sha256sum }}
{{- with .Values.podAnnotations }}
{{- toYaml . | nindent 8 }}
{{- end }}
spec:
serviceAccountName: {{ include "knowledge-platform.serviceAccountName" . }}
automountServiceAccountToken: false
terminationGracePeriodSeconds: {{ .Values.worker.terminationGracePeriodSeconds }}
securityContext:
{{- include "knowledge-platform.podSecurityContext" . | nindent 8 }}
{{- with .Values.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: worker
image: {{ include "knowledge-platform.image" .Values.images.worker | quote }}
imagePullPolicy: {{ .Values.images.worker.pullPolicy }}
workingDir: /tmp
command: ["celery"]
args:
- --app=ekp_api.worker:celery_app
- worker
- --loglevel=INFO
- --queues=ingestion
securityContext:
{{- include "knowledge-platform.containerSecurityContext" . | nindent 12 }}
envFrom:
{{- include "knowledge-platform.envFrom" . | nindent 12 }}
startupProbe:
exec:
command: ["python", "-c", "import os; os.kill(1, 0)"]
{{- toYaml .Values.worker.probes.startup | nindent 12 }}
livenessProbe:
exec:
command: ["python", "-c", "import os; os.kill(1, 0)"]
{{- toYaml .Values.worker.probes.liveness | nindent 12 }}
resources:
{{- toYaml .Values.worker.resources | nindent 12 }}
volumeMounts:
{{- include "knowledge-platform.tmpMount" . | nindent 12 }}
volumes:
{{- include "knowledge-platform.tmpVolume" . | nindent 8 }}

View File

@ -0,0 +1,338 @@
{
"$schema": "https://json-schema.org/draft-07/schema#",
"title": "Enterprise Knowledge Platform Helm values",
"type": "object",
"additionalProperties": false,
"required": [
"existingSecret",
"images",
"serviceAccount",
"api",
"mcp",
"worker",
"scheduler",
"migration",
"ingress",
"config",
"rabbitmq"
],
"properties": {
"nameOverride": {"type": "string"},
"fullnameOverride": {"type": "string"},
"existingSecret": {"$ref": "#/definitions/kubernetesName"},
"imagePullSecrets": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["name"],
"properties": {"name": {"$ref": "#/definitions/kubernetesName"}}
}
},
"images": {
"type": "object",
"additionalProperties": false,
"required": ["api", "mcp", "worker"],
"properties": {
"api": {"$ref": "#/definitions/image"},
"mcp": {"$ref": "#/definitions/image"},
"worker": {"$ref": "#/definitions/image"}
}
},
"serviceAccount": {
"type": "object",
"additionalProperties": false,
"required": ["create", "name", "annotations"],
"properties": {
"create": {"type": "boolean"},
"name": {"type": "string"},
"annotations": {"$ref": "#/definitions/stringMap"}
}
},
"podAnnotations": {"$ref": "#/definitions/stringMap"},
"podLabels": {"$ref": "#/definitions/stringMap"},
"api": {"$ref": "#/definitions/httpWorkload"},
"mcp": {"$ref": "#/definitions/httpWorkload"},
"worker": {
"type": "object",
"additionalProperties": false,
"required": ["replicaCount", "terminationGracePeriodSeconds", "resources", "probes"],
"properties": {
"replicaCount": {"type": "integer", "minimum": 1, "maximum": 100},
"terminationGracePeriodSeconds": {"type": "integer", "minimum": 30, "maximum": 3600},
"resources": {"$ref": "#/definitions/resources"},
"probes": {"$ref": "#/definitions/processProbes"}
}
},
"scheduler": {
"type": "object",
"additionalProperties": false,
"required": ["enabled", "resources", "probes"],
"properties": {
"enabled": {"type": "boolean"},
"resources": {"$ref": "#/definitions/resources"},
"probes": {"$ref": "#/definitions/processProbes"}
}
},
"migration": {
"type": "object",
"additionalProperties": false,
"required": ["enabled", "activeDeadlineSeconds", "backoffLimit", "ttlSecondsAfterFinished", "resources"],
"properties": {
"enabled": {"type": "boolean"},
"activeDeadlineSeconds": {"type": "integer", "minimum": 60, "maximum": 3600},
"backoffLimit": {"type": "integer", "minimum": 0, "maximum": 3},
"ttlSecondsAfterFinished": {"type": "integer", "minimum": 0},
"resources": {"$ref": "#/definitions/resources"}
}
},
"ingress": {
"type": "object",
"additionalProperties": false,
"required": ["enabled", "className", "annotations", "api", "mcp"],
"properties": {
"enabled": {"type": "boolean"},
"className": {"type": "string", "minLength": 1},
"annotations": {"$ref": "#/definitions/stringMap"},
"api": {"$ref": "#/definitions/ingressRoute"},
"mcp": {"$ref": "#/definitions/ingressRoute"}
}
},
"config": {
"type": "object",
"additionalProperties": false,
"required": ["appName", "logLevel", "database", "ingestion", "objectStorage", "chunking", "embedding", "vectorStore", "retrieval", "reranker", "mcp"],
"properties": {
"appName": {"type": "string", "minLength": 1},
"logLevel": {"enum": ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]},
"database": {"$ref": "#/definitions/databaseConfig"},
"ingestion": {"$ref": "#/definitions/ingestionConfig"},
"objectStorage": {"$ref": "#/definitions/objectStorageConfig"},
"chunking": {"$ref": "#/definitions/chunkingConfig"},
"embedding": {"$ref": "#/definitions/embeddingConfig"},
"vectorStore": {"$ref": "#/definitions/vectorStoreConfig"},
"retrieval": {"$ref": "#/definitions/retrievalConfig"},
"reranker": {"$ref": "#/definitions/rerankerConfig"},
"mcp": {"$ref": "#/definitions/mcpConfig"}
}
},
"rabbitmq": {
"type": "object",
"required": ["enabled", "existingSecret"],
"properties": {
"enabled": {"type": "boolean"},
"existingSecret": {"$ref": "#/definitions/kubernetesName"}
}
}
},
"definitions": {
"kubernetesName": {
"type": "string",
"minLength": 1,
"maxLength": 253,
"pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$"
},
"stringMap": {
"type": "object",
"additionalProperties": {"type": "string"}
},
"image": {
"type": "object",
"additionalProperties": false,
"required": ["repository", "tag", "digest", "pullPolicy"],
"properties": {
"repository": {"type": "string", "minLength": 1},
"tag": {"type": "string", "minLength": 1, "not": {"enum": ["latest"]}},
"digest": {"type": "string", "pattern": "^$|^sha256:[a-f0-9]{64}$"},
"pullPolicy": {"enum": ["Always", "IfNotPresent", "Never"]}
}
},
"probeTiming": {
"type": "object",
"additionalProperties": false,
"required": ["failureThreshold", "periodSeconds"],
"properties": {
"failureThreshold": {"type": "integer", "minimum": 1},
"periodSeconds": {"type": "integer", "minimum": 1},
"timeoutSeconds": {"type": "integer", "minimum": 1}
}
},
"httpProbes": {
"type": "object",
"additionalProperties": false,
"required": ["startup", "readiness", "liveness"],
"properties": {
"startup": {"$ref": "#/definitions/probeTiming"},
"readiness": {"$ref": "#/definitions/probeTiming"},
"liveness": {"$ref": "#/definitions/probeTiming"}
}
},
"processProbes": {
"type": "object",
"additionalProperties": false,
"required": ["startup", "liveness"],
"properties": {
"startup": {"$ref": "#/definitions/probeTiming"},
"liveness": {"$ref": "#/definitions/probeTiming"}
}
},
"resources": {
"type": "object",
"additionalProperties": false,
"required": ["requests", "limits"],
"properties": {
"requests": {"$ref": "#/definitions/resourcePair"},
"limits": {"$ref": "#/definitions/resourcePair"}
}
},
"resourcePair": {
"type": "object",
"additionalProperties": false,
"required": ["cpu", "memory"],
"properties": {
"cpu": {"type": ["string", "number"]},
"memory": {"type": "string", "minLength": 2}
}
},
"httpWorkload": {
"type": "object",
"additionalProperties": false,
"required": ["replicaCount", "service", "resources", "probes"],
"properties": {
"replicaCount": {"type": "integer", "minimum": 2, "maximum": 100},
"service": {
"type": "object",
"additionalProperties": false,
"required": ["type", "port"],
"properties": {
"type": {"enum": ["ClusterIP"]},
"port": {"type": "integer", "minimum": 1, "maximum": 65535}
}
},
"resources": {"$ref": "#/definitions/resources"},
"probes": {"$ref": "#/definitions/httpProbes"}
}
},
"ingressRoute": {
"type": "object",
"additionalProperties": false,
"required": ["host", "path", "tlsSecretName"],
"properties": {
"host": {"type": "string", "minLength": 1},
"path": {"type": "string", "pattern": "^/"},
"tlsSecretName": {"$ref": "#/definitions/kubernetesName"}
}
},
"databaseConfig": {
"type": "object",
"additionalProperties": false,
"required": ["poolSize", "maxOverflow", "poolRecycleSeconds", "poolTimeoutSeconds", "connectTimeoutSeconds"],
"properties": {
"poolSize": {"type": "integer", "minimum": 1, "maximum": 100},
"maxOverflow": {"type": "integer", "minimum": 0, "maximum": 100},
"poolRecycleSeconds": {"type": "integer", "minimum": 1},
"poolTimeoutSeconds": {"type": "number", "exclusiveMinimum": 0},
"connectTimeoutSeconds": {"type": "integer", "minimum": 1}
}
},
"ingestionConfig": {
"type": "object",
"additionalProperties": false,
"required": ["maxAttempts", "retryBackoffSeconds", "retryBackoffMaxSeconds", "workerLeaseSeconds", "recoveryIntervalSeconds", "batchMaxFiles", "batchMaxTotalBytes", "maxUploadBytes"],
"properties": {
"maxAttempts": {"type": "integer", "minimum": 1, "maximum": 10},
"retryBackoffSeconds": {"type": "integer", "minimum": 1},
"retryBackoffMaxSeconds": {"type": "integer", "minimum": 1},
"workerLeaseSeconds": {"type": "integer", "minimum": 30},
"recoveryIntervalSeconds": {"type": "integer", "minimum": 5},
"batchMaxFiles": {"type": "integer", "minimum": 1, "maximum": 100},
"batchMaxTotalBytes": {"type": "integer", "minimum": 1},
"maxUploadBytes": {"type": "integer", "minimum": 1}
}
},
"objectStorageConfig": {
"type": "object",
"additionalProperties": false,
"required": ["provider", "endpoint", "bucket", "keyPrefix", "timeoutSeconds"],
"properties": {
"provider": {"const": "bos"},
"endpoint": {"type": "string", "minLength": 1},
"bucket": {"type": "string", "minLength": 1},
"keyPrefix": {"type": "string", "minLength": 1},
"timeoutSeconds": {"type": "number", "exclusiveMinimum": 0}
}
},
"chunkingConfig": {
"type": "object",
"additionalProperties": false,
"required": ["maxTokens", "overlapTokens", "maxCharacters"],
"properties": {
"maxTokens": {"type": "integer", "minimum": 1},
"overlapTokens": {"type": "integer", "minimum": 0},
"maxCharacters": {"type": "integer", "minimum": 4}
}
},
"embeddingConfig": {
"type": "object",
"additionalProperties": false,
"required": ["provider", "model", "endpoint", "timeoutSeconds"],
"properties": {
"provider": {"const": "qianfan"},
"model": {"const": "bge-large-zh"},
"endpoint": {"type": "string", "minLength": 1},
"timeoutSeconds": {"type": "number", "exclusiveMinimum": 0}
}
},
"vectorStoreConfig": {
"type": "object",
"additionalProperties": false,
"required": ["provider", "uri", "user", "database", "table", "index", "batchSize", "timeoutSeconds"],
"properties": {
"provider": {"const": "oceanbase"},
"uri": {"type": "string", "minLength": 1},
"user": {"type": "string", "minLength": 1},
"database": {"type": "string", "minLength": 1},
"table": {"type": "string", "minLength": 1},
"index": {"type": "string", "minLength": 1},
"batchSize": {"type": "integer", "minimum": 1, "maximum": 1000},
"timeoutSeconds": {"type": "number", "exclusiveMinimum": 0}
}
},
"retrievalConfig": {
"type": "object",
"additionalProperties": false,
"required": ["indexProfileId", "denseTopN", "searchTopK"],
"properties": {
"indexProfileId": {"type": "string", "minLength": 1},
"denseTopN": {"type": "integer", "minimum": 1, "maximum": 64},
"searchTopK": {"type": "integer", "minimum": 1, "maximum": 64}
}
},
"rerankerConfig": {
"type": "object",
"additionalProperties": false,
"required": ["provider", "model", "endpoint", "timeoutSeconds"],
"properties": {
"provider": {"const": "qianfan"},
"model": {"const": "bce-reranker-base"},
"endpoint": {"type": "string", "minLength": 1},
"timeoutSeconds": {"type": "number", "exclusiveMinimum": 0}
}
},
"mcpConfig": {
"type": "object",
"additionalProperties": false,
"required": ["publicUrl", "issuerUrl", "clientId", "serviceIdentity", "requiredScope", "allowedHosts", "allowedOrigins", "maxRequestBodyBytes"],
"properties": {
"publicUrl": {"type": "string", "pattern": "^https://"},
"issuerUrl": {"type": "string", "pattern": "^https://"},
"clientId": {"type": "string", "minLength": 1},
"serviceIdentity": {"type": "string", "minLength": 1},
"requiredScope": {"const": "knowledge:search"},
"allowedHosts": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
"allowedOrigins": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "^https://"}},
"maxRequestBodyBytes": {"type": "integer", "minimum": 1024, "maximum": 4194304}
}
}
}
}

View File

@ -0,0 +1,218 @@
# DEPLOY-002 safe defaults. Real endpoints, immutable image coordinates and
# Secret names are supplied in an environment-specific values file.
nameOverride: ""
fullnameOverride: ""
existingSecret: knowledge-platform-runtime
imagePullSecrets: []
images:
api:
repository: knowledge-platform/enterprise-knowledge-api
tag: "0.1.0"
digest: ""
pullPolicy: IfNotPresent
mcp:
repository: knowledge-platform/enterprise-knowledge-mcp
tag: "0.1.0"
digest: ""
pullPolicy: IfNotPresent
worker:
repository: knowledge-platform/enterprise-knowledge-worker
tag: "0.1.0"
digest: ""
pullPolicy: IfNotPresent
serviceAccount:
create: true
name: ""
annotations: {}
podAnnotations: {}
podLabels: {}
api:
replicaCount: 2
service:
type: ClusterIP
port: 80
resources:
requests:
cpu: 250m
memory: 512Mi
limits:
cpu: "1"
memory: 1Gi
probes:
startup:
failureThreshold: 30
periodSeconds: 2
readiness:
periodSeconds: 10
timeoutSeconds: 2
failureThreshold: 3
liveness:
periodSeconds: 20
timeoutSeconds: 2
failureThreshold: 3
mcp:
replicaCount: 2
service:
type: ClusterIP
port: 80
resources:
requests:
cpu: 250m
memory: 512Mi
limits:
cpu: "1"
memory: 1Gi
probes:
startup:
failureThreshold: 30
periodSeconds: 2
readiness:
periodSeconds: 10
timeoutSeconds: 2
failureThreshold: 3
liveness:
periodSeconds: 20
timeoutSeconds: 2
failureThreshold: 3
worker:
replicaCount: 2
terminationGracePeriodSeconds: 60
resources:
requests:
cpu: 500m
memory: 1Gi
limits:
cpu: "2"
memory: 2Gi
probes:
startup:
failureThreshold: 30
periodSeconds: 2
liveness:
periodSeconds: 20
timeoutSeconds: 2
failureThreshold: 3
# Celery Beat is separated from scalable workers so only one recovery
# scheduler publishes due durable Jobs at a time.
scheduler:
enabled: true
resources:
requests:
cpu: 100m
memory: 256Mi
limits:
cpu: 500m
memory: 512Mi
probes:
startup:
failureThreshold: 30
periodSeconds: 2
liveness:
periodSeconds: 20
timeoutSeconds: 2
failureThreshold: 3
migration:
enabled: true
activeDeadlineSeconds: 600
backoffLimit: 0
ttlSecondsAfterFinished: 86400
resources:
requests:
cpu: 100m
memory: 256Mi
limits:
cpu: 500m
memory: 512Mi
ingress:
enabled: false
className: nginx
annotations: {}
api:
host: knowledge.example.invalid
path: /
tlsSecretName: knowledge-platform-api-tls
mcp:
host: mcp.example.invalid
path: /mcp
tlsSecretName: knowledge-platform-mcp-tls
# Only non-sensitive runtime settings belong here. The templates enumerate
# keys explicitly so credentials cannot be added to this ConfigMap by mistake.
config:
appName: enterprise-knowledge-platform
logLevel: INFO
database:
poolSize: 10
maxOverflow: 10
poolRecycleSeconds: 600
poolTimeoutSeconds: 30
connectTimeoutSeconds: 30
ingestion:
maxAttempts: 3
retryBackoffSeconds: 2
retryBackoffMaxSeconds: 60
workerLeaseSeconds: 300
recoveryIntervalSeconds: 30
batchMaxFiles: 20
batchMaxTotalBytes: 209715200
maxUploadBytes: 52428800
objectStorage:
provider: bos
endpoint: https://s3.example.invalid
bucket: knowledge-platform
keyPrefix: knowledge-platform
timeoutSeconds: 30
chunking:
maxTokens: 450
overlapTokens: 75
maxCharacters: 2000
embedding:
provider: qianfan
model: bge-large-zh
endpoint: https://qianfan.baidubce.com/v2/embeddings
timeoutSeconds: 30
vectorStore:
provider: oceanbase
uri: oceanbase.example.invalid:2881
user: knowledge-platform
database: knowledge_platform
table: knowledge_chunks_v1
index: vidx_knowledge_chunks_embedding
batchSize: 100
timeoutSeconds: 30
retrieval:
indexProfileId: demo-bge-large-zh-structure-v1-oceanbase-v1
denseTopN: 20
searchTopK: 5
reranker:
provider: qianfan
model: bce-reranker-base
endpoint: https://qianfan.baidubce.com/v2/rerank
timeoutSeconds: 30
mcp:
publicUrl: https://mcp.example.invalid/mcp
issuerUrl: https://mcp.example.invalid
clientId: workbuddy-enterprise
serviceIdentity: workbuddy-public-knowledge
requiredScope: knowledge:search
allowedHosts:
- mcp.example.invalid
allowedOrigins:
- https://mcp.example.invalid
maxRequestBodyBytes: 1048576
# Optional local dependency. Keep disabled for production and provide
# RABBITMQ_URL through existingSecret for an externally managed broker.
rabbitmq:
enabled: false
existingSecret: knowledge-platform-rabbitmq

View File

@ -211,6 +211,9 @@ Celery task 只负责恢复应用上下文并调用 Ingestion Application Servic
清理顺序和业务幂等仍由应用层持有。Broker 消息不是 Job 的 source of truth,Worker 重启或消息
重复投递必须以 OceanBase 中的持久化 Job/Attempt 状态收敛。
DEPLOY-001 将 API/Admin、MCP Gateway 与 Async Worker 构建为三个共享锁定 Python 运行时的
非 root 镜像 target;进程边界与上述模块边界一致,不新增服务或把 Provider 配置烘焙进镜像。
---
### 4.3 文档结构与 Chunk
@ -760,6 +763,11 @@ readiness/liveness、资源限制、非 root 与只读根文件系统、多副
本地开发资产,不能作为集群模板。详细依赖和验收见
[`PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](../plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md)。
DEPLOY-002 的运行拓扑将 Celery Worker 与 Celery Beat 恢复调度器拆成独立 Pod:Worker 可横向
扩缩,Beat 固定单副本并使用 `Recreate`,避免每个 Worker 都发布周期恢复消息。二者仍调用同一
应用服务与持久化 Job/Attempt 状态,不形成新业务服务,也不改变 ADR-002。Migration 使用 Helm
`pre-install,pre-upgrade` Hook;失败会在业务 Deployment 更新前终止原子升级。
---
## 17. V1 验收重点

View File

@ -0,0 +1,91 @@
# 生产容器镜像说明
## 范围
DEPLOY-001 使用同一个锁定运行时构建三个独立镜像目标:
| Target | 默认镜像名 | 入口 | 端口 | 镜像健康检查 |
|---|---|---|---|---|
| `api` | `enterprise-knowledge-api` | Uvicorn + API/Admin | `8000` | `GET /healthz` |
| `mcp` | `enterprise-knowledge-mcp` | `ekp-mcp` | `8766` | PID 1 存活 |
| `worker` | `enterprise-knowledge-worker` | `ekp-worker` | 无 | PID 1 存活 |
镜像没有内置数据库迁移、Helm、Ingress 或 Secret 对象;DEPLOY-002 已在独立 Chart 中提供这些
编排能力。API 镜像包含 Alembic 和 migrations,由一次性 Migration Job 覆盖命令后复用。详见
[`KUBERNETES_DEPLOYMENT.md`](KUBERNETES_DEPLOYMENT.md)。
## 可重复构建基线
- Python 基础镜像固定为 `3.12.14-slim-bookworm`,uv 固定为 `0.12.5`,两者同时锁定 manifest
digest;
- Python 依赖只使用提交的 `uv.lock`,以 `uv sync --frozen --no-dev --no-editable` 安装;
- 三个目标共享相同依赖层,不复制不同版本的业务运行时;
- 进程均以固定 UID/GID `10001:10001` 运行,不具备 root 权限;
- `.dockerignore` 排除 `.env`、Git、虚拟环境、缓存、本地存储、测试和开发产物;
- Bake 计划同时声明 `linux/amd64` 与 `linux/arm64`,不下载或打包平台专属模型。
基础镜像 tag/digest 与应用依赖均已固定;镜像发布系统仍应保存本项目镜像的构建 digest,并让
Helm 按 digest 部署。本项目镜像 digest 由实际 Registry 发布产生,不把某个环境的 Registry
地址写入仓库。
## 构建命令
先确认 Docker Buildx builder 支持两个目标平台:
```bash
make images-print
```
构建全部目标:
```bash
IMAGE_REGISTRY=registry.example.internal/knowledge \
IMAGE_TAG=<immutable-release-tag> \
make images
```
只有发布流水线才执行推送:
```bash
IMAGE_REGISTRY=registry.example.internal/knowledge \
IMAGE_TAG=<immutable-release-tag> \
make images-push
```
不要把 Registry 密码放入变量或命令行;构建节点应提前通过其凭据助手登录。禁止使用
`latest` 作为集群部署版本。
## 运行时配置
镜像只内置以下非敏感进程默认值:`APP_ENV=production`、容器监听地址、静态页面绝对路径和
临时缓存目录。OceanBase、BOS、RabbitMQ、Embedding、Reranker 与 MCP Token 必须在容器启动
时由 Secret 注入。镜像构建参数、Layer、标签、健康检查和启动命令都不得包含这些值。
API 的 `/healthz` 只证明进程存活,不读取云端凭据或探测依赖。Kubernetes readiness、资源限制、
只读根文件系统所需临时卷及依赖就绪策略由 DEPLOY-002 Chart 配置。MCP endpoint 需要认证,Worker
没有 HTTP server,因此这两个镜像的 Docker 健康检查只验证主进程;业务可恢复性仍以持久化
Job/Attempt 和 DEPLOY-003 故障验收为准。
## 本地单目标检查
需要加载到本地 Docker 时,可直接构建当前平台的一个 target:
```bash
docker build --target api -f deploy/docker/Dockerfile -t ekp-api:test .
docker build --target mcp -f deploy/docker/Dockerfile -t ekp-mcp:test .
docker build --target worker -f deploy/docker/Dockerfile -t ekp-worker:test .
```
启动时使用 `--env-file` 或编排系统的 Secret 引用,不在命令中展开敏感值。API/Admin smoke test
至少检查 `/healthz`、`/admin/upload` 和 `/api/v1/openapi.json`;MCP 与 Worker 的真实依赖启动
验收在具备 RabbitMQ 和目标 Provider 的受控环境执行。
## DEPLOY-001 构建验收
2026-09-02 已使用 Buildx 分别构建并加载三个 `linux/arm64` target 和三个 `linux/amd64`
target。API/Admin 以非 root 用户完成健康、静态页面和 OpenAPI smoke test;MCP/Worker 完成非
root 安装入口检查。构建历史与容器文件系统检查未发现 `.env`、Git、测试文件或敏感配置。
这次验收只生成本地 `deploy001-*` 测试 tag,没有登录或推送 Registry,因此不产生可供集群
引用的项目镜像 digest。DEPLOY-002 必须使用操作者指定的不可变 Registry tag/digest,不得把
本地测试 tag 当作发布版本。

View File

@ -0,0 +1,143 @@
# Kubernetes / Helm 部署说明
## 1. 交付范围
DEPLOY-002 提供单一 Helm Chart,将以下运行角色部署到已有 Kubernetes 集群:
- API/Admin:默认两个副本,提供 `/healthz`、`/admin/*` 和 `/api/v1/*`;
- MCP Gateway:默认两个副本,提供经 Bearer Token 保护的 `/mcp`;
- Async Worker:默认两个副本,只消费 `ingestion` 队列;
- Recovery Scheduler:固定单副本,以 `Recreate` 策略运行 Celery Beat;
- Migration Job:每次安装/升级前串行执行 `alembic upgrade head`;
- 可选 RabbitMQ:只供开发/演示集群显式启用,生产默认使用外部 Broker。
OceanBase MySQL、BOS、Embedding/Reranker 服务继续使用集群外已有资源。Chart 不创建数据库、
BOS Bucket、域名、证书或云账号,也没有扩大公共知识库阶段的业务范围。
## 2. 前置条件
操作者需要提前准备:
1. 可用的 Kubernetes Namespace 和对应 `kubectl` 上下文;
2. Helm 3/4 与 Kubernetes 客户端;
3. 已推送到目标 Registry 的 API、MCP、Worker 不可变 tag 或 digest;
4. Namespace 内的运行时 Secret、TLS Secret,以及私有 Registry 所需的 ImagePullSecret;
5. 集群到 OceanBase、BOS、RabbitMQ 和模型服务的网络连通性。
Chart 默认引用 `knowledge-platform-runtime`,但不会创建它。该 Secret 至少包含以下键:
```text
DATABASE_URL
RABBITMQ_URL
BOS_ACCESS_KEY_ID
BOS_SECRET_ACCESS_KEY
BAIDU_QIANFAN_API_KEY
OCEANBASE_VECTOR_PASSWORD
MCP_AUTH_TOKEN
```
`RERANKER_API_KEY` 可单独提供;未提供时应用按既有契约复用
`BAIDU_QIANFAN_API_KEY`。`MCP_AUTH_TOKEN` 至少 32 个字符,只具备
`knowledge:search` 服务范围。不要使用 `kubectl --from-literal`、Shell 参数或 Helm
`--set` 传递以上值;应由受控 Secret 管理系统或运维流程预先写入 Namespace。
## 3. 环境 Values
复制 [`values.example.yaml`](../../deploy/helm/environments/values.example.yaml) 到仓库外的受控
路径,填写以下非敏感信息:
- 三个镜像的 Registry 路径与不可变 tag/digest;
- `existingSecret` 和 `imagePullSecrets` 的资源名称;
- OceanBase/BOS 的非敏感 Endpoint、数据库标识和 Bucket;
- Admin/API 与 MCP 的 Ingress Host、TLS Secret 名称;
- 与外部地址一致的 MCP Public URL、Issuer、Allowed Host/Origin;
- 副本、资源、超时和批量上传限制。
`values.schema.json` 拒绝未知顶层字段、`latest` tag、无效 digest、单副本 API/MCP、错误类型和
空的关键引用;模板还会校验 Chunk、检索和入库限制之间的大小关系。Values 只允许非敏感配置,
模板逐项生成 ConfigMap,不提供任意 `extraEnv` 入口,避免把凭据误写进渲染产物。
## 4. 安装与幂等升级
先做离线校验和清单检查:
```bash
make deploy-lint VALUES=/secure/path/environment-values.yaml
make deploy-render VALUES=/secure/path/environment-values.yaml
```
安装或升级:
```bash
NAMESPACE=knowledge-platform \
RELEASE=knowledge-platform \
make deploy VALUES=/secure/path/environment-values.yaml
```
`make deploy` 只接收 Values 文件路径。脚本会先验证 Chart、Namespace、运行时 Secret 及必需
键名、可选 RabbitMQ Secret 键名,以及启用 Ingress 时的两个 TLS Secret 引用,然后执行带失败
回滚和等待语义的 `helm upgrade --install`;脚本对 Helm 3 使用 `--atomic`,对 Helm 4 使用等价
的 `--rollback-on-failure`。它只验证 Secret 资源和键是否存在,不读取或输出 Secret 值。
Migration 是 `pre-install,pre-upgrade` Hook,固定名称配合
`before-hook-creation` 保证同一 Release 内不会并发执行。Helm 等待 Migration 成功后才更新业务
工作负载;失败时 Helm 保留上一版本。完成的 Job 最长保留一天供日志追查,并在下次升级前删除。
安装命令可以重复执行;数据库迁移必须保持 forward-only 与幂等。
## 5. Ingress、探针与 Pod 安全
生产环境启用 Ingress 后,Admin/API 与 MCP 使用独立稳定 HTTPS Host,也可由同一 Ingress
Controller 托管。证书只通过预建 TLS Secret 引用,不进入 Values。
- API 的 startup/readiness/liveness 调用无凭据 `/healthz`;
- MCP 的三类探针使用 TCP 端口,不发送或记录 Token;
- Worker/Scheduler 使用 PID 1 存活探针,业务恢复正确性由持久化 Job/Attempt 保证;
- 全部应用容器固定 UID/GID `10001`、禁止提权、丢弃 Linux capabilities、使用
`RuntimeDefault` seccomp 和只读根文件系统;
- `/tmp` 使用有大小上限的 `emptyDir`,ServiceAccount 不挂载 API Token;
- API/MCP 滚动更新使用 `maxUnavailable: 0`,未 Ready Pod 不进入 Service Endpoint。
`/healthz` 当前只表示 API 进程存活,不探测所有外部 Provider;真实依赖故障、滚动重启和
Worker 恢复行为由 DEPLOY-003 在目标集群验收。
## 6. 可选 Demo RabbitMQ
生产默认 `rabbitmq.enabled=false`,`RABBITMQ_URL` 指向外部受管 Broker。仅开发/演示时可开启
本地子 Chart;它使用单节点 StatefulSet 和 PVC,并要求预建 Secret 包含:
```text
username
password
erlang-cookie
```
同时必须让运行时 Secret 中的 `RABBITMQ_URL` 指向该 Service。子 Chart 使用固定
`rabbitmq:4.1.4-alpine` tag 与 multi-architecture manifest digest;它不具备生产 RabbitMQ 的
高可用、备份或升级保证,禁止作为生产默认值。卸载 Release 时 StatefulSet PVC 默认保留,
删除前必须由数据责任人确认。
## 7. 回滚、卸载与 Secret 轮换
查看历史并回滚时不要输出 Pod 环境变量:
```bash
helm -n knowledge-platform history knowledge-platform
helm -n knowledge-platform rollback knowledge-platform <revision> --wait
```
更新外部 Secret 后,Secret 名称不变;用户和 WorkBuddy 配置无需重新注入。当前应通过受控
滚动重启让 Pod 读取新值,目标集群的无中断验证属于 DEPLOY-003。
卸载只删除本 Release 管理的 Kubernetes 对象:
```bash
helm -n knowledge-platform uninstall knowledge-platform
```
外部 OceanBase、BOS、RabbitMQ、TLS/运行时 Secret 和可选 RabbitMQ PVC 不由卸载命令删除。
## 8. DEPLOY-002 验收边界
本任务完成 Chart lint、双路径渲染、严格 Kubernetes Schema、Values 失败关闭、Secret 泄漏扫描
以及本地集群两次安装/升级验证。目标企业集群的稳定 HTTPS、滚动重启、Worker 故障恢复、真实
Provider 和远程 WorkBuddy 验收统一属于后续 `DEPLOY-003`,不得提前宣称完成。

View File

@ -1,12 +1,12 @@
# 项目进度
当前阶段:批量异步上传闭环完成,准备交付生产镜像
当前阶段:生产容器镜像闭环完成,准备实施 Kubernetes/Helm 一键部署
已完成:DEMO-001~DEMO-010、DEMO-012、DEMO-014~DEMO-016、ARCH-001~ARCH-006、PLAN-001~PLAN-002
已完成:DEMO-001~DEMO-010、DEMO-012、DEMO-014~DEMO-016、ARCH-001~ARCH-006、PLAN-001~PLAN-002、DEPLOY-001
进行中:无
阻塞:无
下一任务:`DEPLOY-001`。随后严格执行 `DEPLOY-002 → DEPLOY-003`。
下一任务:`DEPLOY-002`,完成并合并后执行 `DEPLOY-003`。
Provider 架构迁移按 `ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → ARCH-005 → ARCH-006`
执行并已完成。DEMO-010 在迁移闭环验收后实施,未扩大为完整 V1 Admin Console。
@ -377,3 +377,50 @@ Provider 架构迁移按 `ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → AR
- 未扩展目录上传、压缩包解包、断点续传、手动重试、去重、用户或 ACL;自动重试和清理继续
复用 DEMO-015,Accepted ADR 未变更。
- 下一任务:`DEPLOY-001`。
### DEPLOY-001(已完成)
- 新增共享生产 Dockerfile 的 `api`、`mcp`、`worker` 三个 target,使用精确 Python/uv 版本、
frozen production dependencies、固定非 root UID/GID、exec-form 启动命令和逐 target 健康检查。
- 新增 amd64/arm64 Buildx Bake 计划、镜像构建/渲染/推送 Make 入口和 `.dockerignore`;构建上下文
排除凭据、本地状态、缓存、测试与开发产物,镜像不包含环境 Endpoint 或 Secret。
- Admin 静态目录新增类型化运行时覆盖,使非 editable 安装后的 API 镜像仍能提供同源页面;
源码运行继续使用既有默认目录。
- 新增不依赖 Docker daemon 的镜像契约测试与中文运行文档;基础 Python/uv 镜像同时固定精确
tag 与 manifest digest,Registry 地址和本项目发布 digest 继续由部署环境提供。
- 使用 Docker Buildx `0.36.1` + Colima 分别实际构建并加载全部三个 `linux/arm64` 和三个
`linux/amd64` target;最终 digest 固定版本再次构建命中相同业务 layer。没有执行 Registry
push,也没有在构建参数、history 或镜像文件系统中发现凭据。
- API 镜像以 `10001:10001` 启动并进入 healthy,`/healthz`、`/admin/upload`、OpenAPI 及
DEMO-016 批量路径 smoke test 通过;MCP/Worker 镜像以同一非 root 用户完成安装入口导入,
默认 CMD 与 HEALTHCHECK 元数据核对通过。真实 Provider/Broker 启动仍属于 DEPLOY-003。
- Ruff Format/Lint、Mypy、Docker Bake 渲染、JavaScript/依赖锁/Alembic 与完整测试门禁通过;
Unit + Integration `187 passed`,RAG Evaluation `5 passed`。下一任务:`DEPLOY-002`。
### DEPLOY-002(已完成)
- 新增 `deploy/helm/knowledge-platform` Helm Chart,部署 API/Admin、MCP Gateway、Async Worker、
单实例 Recovery Scheduler、串行 Migration Job、Service、Ingress/TLS 和可选 Demo RabbitMQ;
API/MCP 默认各两个副本,Worker 可独立扩缩,Beat 使用 `Recreate` 避免重复调度。
- 新增严格 `values.schema.json` 与仓库外环境 Values 示例,拒绝未知顶层字段、`latest` tag、
非法 digest、API/MCP 单副本和错误类型;跨字段模板校验继续约束批量大小、重试、Chunk 和
Top-K 关系。应用和可选 RabbitMQ 镜像均支持 digest,Demo RabbitMQ 已固定 manifest digest。
- 敏感配置只通过预建 `existingSecret` 注入;ConfigMap 仅渲染显式白名单内的非敏感字段,
没有任意 `extraEnv` 或 Secret 对象。`scripts/deploy.sh` 在部署前校验 Values、Namespace、运行时
Secret/必需键、可选 RabbitMQ Secret/键和启用 Ingress 时的 TLS Secret 引用,不读取 Secret
值;Helm 3/4 分别使用等价的原子失败回滚参数。
- Migration 使用 `pre-install,pre-upgrade` Hook、固定名称和 `before-hook-creation`,安装/升级在
Migration 成功前不更新业务 Pod。应用容器固定非 root UID/GID、只读根文件系统、丢弃全部
capabilities、禁用 ServiceAccount Token,并为临时目录、RabbitMQ 日志和 Beat 状态提供
`emptyDir`;API/MCP/Worker/Scheduler 均配置启动和存活/就绪探针及资源 requests/limits。
- 本机使用 K3s `v1.35.0+k3s1`、Helm `4.2.4` 和 DEPLOY-001 ARM64 镜像完成真实安装;Migration
成功,API/MCP 为 `2/2`,Worker、Scheduler 与可选 RabbitMQ 全部 Ready。首次安装暴露的
RabbitMQ 只读日志目录和 Beat 调度文件权限问题已修复,随后相同 Values 连续升级至 Revision
3~5 均成功;API `/healthz` 和 Admin 上传页 smoke test 通过。
- 默认、环境示例和 RabbitMQ 三种 Helm lint 均通过;含 Ingress/TLS/RabbitMQ 的 14 个最终
资源通过 kubeconform strict 校验。仓库、Helm manifest、Pod 日志三路 Secret 值扫描均为 `0`;
Ruff Format/Lint、Mypy、Alembic、Bash 语法与完整门禁通过,Unit + Integration `195 passed`,
RAG Evaluation `5 passed`。
- 目标企业集群的稳定 HTTPS、滚动重启、Worker 故障恢复、真实外部依赖监测与远程 WorkBuddy
仍属于 `DEPLOY-003`;本任务没有把这些项提前标记完成,也没有改变 Accepted ADR 或公共知识库
范围。下一任务:`DEPLOY-003`。

View File

@ -87,14 +87,16 @@ Celery/RabbitMQ。队列调用保持在抽象边界后,不允许业务服务
### DEPLOY-001
交付 API/Admin、MCP Gateway、Async Worker 的生产容器镜像与启动约定;镜像使用固定依赖、
**已完成。** 交付 API/Admin、MCP Gateway、Async Worker 的生产容器镜像与启动约定;镜像使用固定依赖、
非 root 用户、健康检查和多架构可构建基线,不内置凭据。
### DEPLOY-002
交付 Kubernetes/Helm Chart、环境 Values Schema、`existingSecret`、Migration Job、Ingress/TLS、
Pod 安全、资源限制、探针和 `make deploy` 入口。现有 `docker-compose.dev.yml` 仍仅作为旧的
本地开发文件,因其 PostgreSQL/MinIO 假设与 ADR-012 不一致,不得作为集群交付模板。
**已完成。** 交付 Kubernetes/Helm Chart、严格环境 Values Schema、`existingSecret`、串行
Migration Hook、Ingress/TLS、Pod 安全、资源限制、探针和 `make deploy` 入口;Worker 与单实例
恢复调度器已分离。现有 `docker-compose.dev.yml` 仍仅作为旧的本地开发文件,因其
PostgreSQL/MinIO 假设与 ADR-012 不一致,不得作为集群交付模板。下一交付门槛为 DEPLOY-003
的目标集群可用性与远程验收。
### DEPLOY-003

View File

@ -30,8 +30,8 @@ validation. Provider credentials and internal endpoints are runtime inputs and n
- [x] PLAN-002 公共知识库集群交付范围、任务拆分和一键部署基线
- [x] DEMO-015 Async ingestion Job + Celery/RabbitMQ + bounded retry + pre-retry cleanup
- [x] DEMO-016 Batch async upload API + per-file Job status + Admin Console
- [ ] DEPLOY-001 Production images for API/Admin, MCP Gateway and Async Worker
- [ ] DEPLOY-002 Kubernetes/Helm one-click deployment + Secret/Migration/Ingress baseline
- [x] DEPLOY-001 Production images for API/Admin, MCP Gateway and Async Worker
- [x] DEPLOY-002 Kubernetes/Helm one-click deployment + Secret/Migration/Ingress baseline
- [ ] DEPLOY-003 Availability, rolling upgrade and remote WorkBuddy acceptance
Dependencies and acceptance boundaries are defined in

View File

@ -18,8 +18,8 @@
1. `PLAN-002`:确定公共知识库交付边界、目标拓扑、Task 拆分与验收门槛;
2. `DEMO-015`(已完成):持久化异步 Job、Celery/RabbitMQ 执行器、自动重试和重试前清理;
3. `DEMO-016`(已完成):批量异步上传、批次/Job 查询和 Admin Console 状态展示;
4. `DEPLOY-001`:API/Admin、MCP Gateway、Async Worker 生产镜像;
5. `DEPLOY-002`:Kubernetes/Helm、Secret、Migration、Ingress/TLS 和一键部署入口;
4. `DEPLOY-001`(已完成):API/Admin、MCP Gateway、Async Worker 生产镜像;
5. `DEPLOY-002`(已完成):Kubernetes/Helm、Secret、Migration、Ingress/TLS 和一键部署入口;
6. `DEPLOY-003`:多副本可用性、滚动升级、Worker 恢复和远程 WorkBuddy 验收。
严格依赖为:

View File

@ -468,6 +468,13 @@ Document ID 和 Ingestion Job;单个文件处理失败不得阻塞或回滚批
当前 Demo 已实现多文件 `202` 接收、批次聚合查询和逐文件 Job 状态;目录上传、压缩包解包、
断点续传以及完整 V1 的 Hash/Version/ACL 能力仍按各自 Task 后置。
公共知识库集群交付使用分别可扩缩的 API/Admin、MCP Gateway 和 Async Worker 生产镜像;
镜像只包含锁定代码与非敏感默认值,环境凭据必须在部署时注入。
集群编排由 Helm Chart 统一管理:API/MCP 默认多副本,Worker 与单实例恢复调度器分离;敏感值
只引用预建 Kubernetes Secret,数据库 Migration 在安装/升级前串行完成。Ingress/TLS、探针、
资源限制和 Pod 安全默认值属于部署契约,不改变 REST/MCP 业务接口。
**REQ-INGEST-004**
展示处理阶段:

View File

@ -25,6 +25,7 @@ class Settings(BaseSettings):
api_host: str = "0.0.0.0"
api_port: int = Field(default=8000, ge=1, le=65535)
api_prefix: str = "/api/v1"
admin_web_root: Path | None = None
# SQLAlchemy URLs commonly embed a password, so configuration rendering
# must mask this value and unwrap it only at the database driver boundary.
database_url: SecretStr = SecretStr("mysql+pymysql://localhost:2881/ekp")

130
scripts/deploy.sh Executable file
View File

@ -0,0 +1,130 @@
#!/usr/bin/env bash
set -euo pipefail
# DEPLOY-002 accepts a values file path only. Secret contents remain in
# Kubernetes and are never expanded into this process or Helm arguments.
values_file="${1:-}"
chart_dir="${CHART:-deploy/helm/knowledge-platform}"
release_name="${RELEASE:-knowledge-platform}"
namespace="${NAMESPACE:-knowledge-platform}"
deploy_timeout="${DEPLOY_TIMEOUT:-10m}"
if [[ -z "${values_file}" || ! -f "${values_file}" ]]; then
echo "VALUES must point to an existing environment values file" >&2
exit 2
fi
for tool in helm kubectl; do
if ! command -v "${tool}" >/dev/null 2>&1; then
echo "required deployment tool is missing: ${tool}" >&2
exit 2
fi
done
# Helm 4 renamed --atomic to --rollback-on-failure. Select the equivalent flag
# by major version while preserving compatibility with supported Helm 3.
helm_version="$(helm version --template '{{.Version}}')"
if [[ "${helm_version}" =~ ^v?([0-9]+) ]] && (( BASH_REMATCH[1] >= 4 )); then
rollback_flag=(--rollback-on-failure)
else
rollback_flag=(--atomic)
fi
helm lint "${chart_dir}" --values "${values_file}"
# The test-hook ConfigMap contains resource names only. Its fixed, controlled
# shape lets awk extract names without adding a YAML parser or reading Secrets.
preflight_yaml="$({
helm template "${release_name}" "${chart_dir}" \
--namespace "${namespace}" \
--values "${values_file}" \
--show-only templates/tests/preflight-references.yaml
})"
runtime_secret="$({
printf '%s\n' "${preflight_yaml}" | awk '$1 == "runtimeSecret:" {gsub(/\"/, "", $2); print $2}'
})"
ingress_enabled="$({
printf '%s\n' "${preflight_yaml}" | awk '$1 == "ingressEnabled:" {gsub(/\"/, "", $2); print $2}'
})"
rabbitmq_enabled="$({
printf '%s\n' "${preflight_yaml}" | awk '$1 == "rabbitmqEnabled:" {gsub(/\"/, "", $2); print $2}'
})"
if [[ -z "${runtime_secret}" || -z "${ingress_enabled}" || -z "${rabbitmq_enabled}" ]]; then
echo "failed to resolve Helm Secret references" >&2
exit 2
fi
secret_has_key() {
local secret_name="$1"
local key_name="$2"
local present
present="$({
kubectl -n "${namespace}" get secret "${secret_name}" \
-o go-template="{{with .data}}{{if index . \"${key_name}\"}}present{{end}}{{end}}"
})"
[[ "${present}" == "present" ]]
}
if ! kubectl get namespace "${namespace}" >/dev/null; then
echo "target namespace does not exist: ${namespace}" >&2
exit 2
fi
if ! kubectl -n "${namespace}" get secret "${runtime_secret}" >/dev/null; then
echo "referenced runtime Secret does not exist: ${runtime_secret}" >&2
exit 2
fi
required_runtime_keys=(
DATABASE_URL
RABBITMQ_URL
BOS_ACCESS_KEY_ID
BOS_SECRET_ACCESS_KEY
BAIDU_QIANFAN_API_KEY
OCEANBASE_VECTOR_PASSWORD
MCP_AUTH_TOKEN
)
for key in "${required_runtime_keys[@]}"; do
if ! secret_has_key "${runtime_secret}" "${key}"; then
echo "referenced runtime Secret is missing required key: ${key}" >&2
exit 2
fi
done
if [[ "${ingress_enabled}" == "true" ]]; then
for key in apiTlsSecret mcpTlsSecret; do
tls_secret="$({
printf '%s\n' "${preflight_yaml}" | awk -v field="${key}:" '$1 == field {gsub(/\"/, "", $2); print $2}'
})"
if ! kubectl -n "${namespace}" get secret "${tls_secret}" >/dev/null; then
echo "referenced TLS Secret does not exist: ${tls_secret}" >&2
exit 2
fi
done
fi
if [[ "${rabbitmq_enabled}" == "true" ]]; then
rabbitmq_secret="$({
printf '%s\n' "${preflight_yaml}" | awk '$1 == "rabbitmqSecret:" {gsub(/\"/, "", $2); print $2}'
})"
if ! kubectl -n "${namespace}" get secret "${rabbitmq_secret}" >/dev/null; then
echo "referenced RabbitMQ Secret does not exist: ${rabbitmq_secret}" >&2
exit 2
fi
for key in username password erlang-cookie; do
if ! secret_has_key "${rabbitmq_secret}" "${key}"; then
echo "referenced RabbitMQ Secret is missing required key: ${key}" >&2
exit 2
fi
done
fi
# The version-specific rollback flag keeps the previous release active when a
# pre-upgrade migration or rollout fails. Helm serializes operations for this
# release and waits for hook/workload readiness before returning success.
helm upgrade --install "${release_name}" "${chart_dir}" \
--namespace "${namespace}" \
--values "${values_file}" \
"${rollback_flag[@]}" \
--wait \
--timeout "${deploy_timeout}" \
--history-max 10

View File

@ -14,6 +14,7 @@ def test_settings_have_demo_defaults(isolated_settings_environment: None) -> Non
assert settings.app_env == "development"
assert settings.api_prefix == "/api/v1"
assert settings.api_port == 8000
assert settings.admin_web_root is None
assert settings.database_url.get_secret_value().startswith("mysql+pymysql://")
assert settings.database_pool_size == 10
assert settings.database_max_overflow == 10

View File

@ -0,0 +1,154 @@
"""Static and rendered contracts for the DEPLOY-002 Helm delivery."""
import json
import shutil
import subprocess
from pathlib import Path
import pytest
ROOT = Path(__file__).resolve().parents[2]
CHART = ROOT / "deploy" / "helm" / "knowledge-platform"
EXAMPLE_VALUES = ROOT / "deploy" / "helm" / "environments" / "values.example.yaml"
def _helm(*arguments: str, expect_success: bool = True) -> subprocess.CompletedProcess[str]:
"""Run Helm when installed; static checks still run on Python-only hosts."""
executable = shutil.which("helm")
if executable is None:
pytest.skip("Helm is required for rendered chart assertions")
result = subprocess.run(
[executable, *arguments],
cwd=ROOT,
check=False,
capture_output=True,
text=True,
)
if expect_success and result.returncode != 0:
pytest.fail(f"Helm failed: {result.stderr or result.stdout}")
return result
def _render(*extra_arguments: str) -> str:
"""Render deterministic manifests without contacting a cluster."""
result = _helm(
"template",
"knowledge-platform",
str(CHART),
"--namespace",
"knowledge-platform",
"--values",
str(EXAMPLE_VALUES),
*extra_arguments,
)
return result.stdout
def test_chart_has_machine_validated_values_schemas() -> None:
"""Both the application and optional broker expose valid JSON Schemas."""
for schema_path in (
CHART / "values.schema.json",
CHART / "charts" / "rabbitmq" / "values.schema.json",
):
schema = json.loads(schema_path.read_text())
assert schema["$schema"] == "https://json-schema.org/draft-07/schema#"
assert schema["type"] == "object"
def test_default_chart_renders_secret_only_sensitive_configuration() -> None:
"""Credentials are references; the chart never creates or embeds a Secret."""
rendered = _render()
assert "kind: Secret\n" not in rendered
assert "secretRef:\n name: knowledge-platform-runtime" in rendered
assert "key: DATABASE_URL" in rendered
assert "helm.sh/hook: pre-install,pre-upgrade" in rendered
assert 'args: ["upgrade", "head"]' in rendered
assert "value: mysql+pymysql://" not in rendered
assert "change-me" not in rendered
def test_workloads_render_availability_and_restricted_pod_defaults() -> None:
"""API/MCP are multi-replica and every application process is non-root."""
rendered = _render()
assert "name: knowledge-platform-api" in rendered
assert "name: knowledge-platform-mcp" in rendered
assert rendered.count("replicas: 2") >= 3
assert rendered.count("readOnlyRootFilesystem: true") >= 5
assert rendered.count("allowPrivilegeEscalation: false") >= 5
assert rendered.count("automountServiceAccountToken: false") >= 6
assert "maxUnavailable: 0" in rendered
assert "readinessProbe:" in rendered
assert "livenessProbe:" in rendered
assert "startupProbe:" in rendered
def test_scheduler_is_singleton_and_workers_do_not_embed_beat() -> None:
"""Scaled workers cannot accidentally create multiple periodic schedulers."""
rendered = _render()
scheduler = rendered[rendered.index("name: knowledge-platform-scheduler") :]
scheduler = scheduler[: scheduler.index("---", 1)]
worker = rendered[rendered.index("name: knowledge-platform-worker") :]
worker = worker[: worker.index("---", 1)]
assert "replicas: 1" in scheduler
assert "type: Recreate" in scheduler
assert "- beat" in scheduler
assert "- worker" in worker
assert "- beat" not in worker
def test_ingress_and_optional_rabbitmq_are_explicitly_renderable() -> None:
"""TLS routes and the persistent demo broker remain opt-in values."""
rendered = _render("--set", "rabbitmq.enabled=true")
assert "kind: Ingress" in rendered
assert "secretName: knowledge-platform-api-tls" in rendered
assert "secretName: knowledge-platform-mcp-tls" in rendered
assert "kind: StatefulSet" in rendered
assert "volumeClaimTemplates:" in rendered
assert "name: RABBITMQ_DEFAULT_PASS" in rendered
assert "valueFrom:" in rendered
def test_values_schema_rejects_latest_image_tags() -> None:
"""Cluster releases require a non-latest immutable tag or digest."""
result = _helm(
"lint",
str(CHART),
"--set",
"images.api.tag=latest",
expect_success=False,
)
assert result.returncode != 0
assert "/images/api/tag" in (result.stdout + result.stderr)
def test_cross_field_validation_rejects_unsafe_ingestion_limits() -> None:
"""Rendered settings preserve the application's own configuration rules."""
result = _helm(
"template",
"knowledge-platform",
str(CHART),
"--set",
"config.ingestion.batchMaxTotalBytes=1",
expect_success=False,
)
assert result.returncode != 0
assert "batchMaxTotalBytes must be >= maxUploadBytes" in (result.stdout + result.stderr)
def test_deploy_entrypoint_uses_atomic_upgrade_and_never_reads_secret_values() -> None:
"""The one-command wrapper checks references and performs an atomic wait."""
script = (ROOT / "scripts" / "deploy.sh").read_text()
assert "helm upgrade --install" in script
assert "--atomic" in script
assert "--rollback-on-failure" in script
assert "--wait" in script
assert 'kubectl -n "${namespace}" get secret' in script
assert 'awk \'$1 == "runtimeSecret:"' in script
assert "DATABASE_URL}'" not in script

View File

@ -0,0 +1,65 @@
"""Static production-image contract tests that do not require a Docker daemon."""
from pathlib import Path
PROJECT_ROOT = Path(__file__).resolve().parents[2]
DOCKERFILE = PROJECT_ROOT / "deploy/docker/Dockerfile"
BAKE_FILE = PROJECT_ROOT / "deploy/docker/docker-bake.hcl"
def test_runtime_is_locked_non_root_and_secret_free() -> None:
"""Guard the supply-chain and least-privilege choices in the shared runtime."""
dockerfile = DOCKERFILE.read_text()
assert "python:3.12.14-slim-bookworm" in dockerfile
assert "ghcr.io/astral-sh/uv:0.12.5" in dockerfile
assert dockerfile.count("@sha256:") == 2
assert "uv sync --frozen --no-dev --no-editable" in dockerfile
assert "USER 10001:10001" in dockerfile
assert "COPY . " not in dockerfile
assert all(
sensitive not in dockerfile
for sensitive in ("DATABASE_URL=", "RABBITMQ_URL=", "API_KEY=", "PASSWORD=")
)
def test_three_process_targets_have_healthchecks_and_exec_commands() -> None:
"""Every independently deployed process must have an explicit runtime contract."""
dockerfile = DOCKERFILE.read_text()
assert dockerfile.count("HEALTHCHECK ") == 3
assert "FROM runtime AS api" in dockerfile
assert "FROM runtime AS mcp" in dockerfile
assert "FROM runtime AS worker" in dockerfile
assert 'CMD ["uvicorn", "ekp_api.main:app"' in dockerfile
assert 'CMD ["ekp-mcp"]' in dockerfile
assert 'CMD ["ekp-worker"]' in dockerfile
def test_bake_plan_covers_both_architectures_and_all_images() -> None:
"""The checked-in build plan must stay suitable for amd64 and arm64 clusters."""
bake = BAKE_FILE.read_text()
assert 'platforms = ["linux/amd64", "linux/arm64"]' in bake
assert 'context = "."' in bake
assert 'targets = ["api", "mcp", "worker"]' in bake
assert bake.count('inherits = ["common"]') == 3
assert all(
image in bake
for image in (
"enterprise-knowledge-api",
"enterprise-knowledge-mcp",
"enterprise-knowledge-worker",
)
)
def test_docker_context_excludes_credentials_and_local_state() -> None:
"""Prevent common developer files from entering any build layer."""
ignored = (PROJECT_ROOT / ".dockerignore").read_text().splitlines()
assert ".env" in ignored
assert ".git" in ignored
assert ".venv" in ignored
assert "storage" in ignored
assert "tests" in ignored