diff --git a/README.md b/README.md index dac38a6..9f17ff3 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## 从这里开始 -先阅读 [Ubuntu 22.04 本地部署运行手册](docs/DEPLOYMENT-RUNBOOK.md)、[后端本地部署](docs/BACKEND-DEPLOYMENT.md)、[样机硬件评估报告](docs/POC-HARDWARE-BASELINE.md) 和 [源码版本核对](docs/SOURCE-RECONCILIATION.md)。当前可以启动 PostgreSQL、Redis、MinIO 和平台后端;平台前端、管理端 AI-only 模式和统一网关仍在后续阶段。 +先阅读 [Ubuntu 22.04 本地部署运行手册](docs/DEPLOYMENT-RUNBOOK.md)、[后端本地部署](docs/BACKEND-DEPLOYMENT.md)、[平台前端本地部署](docs/FRONTEND-DEPLOYMENT.md)、[样机硬件评估报告](docs/POC-HARDWARE-BASELINE.md) 和 [源码版本核对](docs/SOURCE-RECONCILIATION.md)。当前可以启动 PostgreSQL、Redis、MinIO、平台后端和平台前端;管理端 AI-only 模式和统一网关仍在后续阶段。 本仓库是 AI SoulMate 私有化部署的编排与留档仓库,用于固定源码版本、记录硬件基线、建设部署配置并沉淀压测结果。业务源码仍保留在各自仓库中,不复制源码、不改写原有 Git 历史。 @@ -32,7 +32,7 @@ - `docs/CROSS-COMPUTER-HANDOFF.md`:换电脑继续工作的状态、重建 Git 和接管清单。 - `decisions/`:影响交付方式的架构决策。 - `inventory/`:参与部署的源码版本清单。 -- `compose/`:基础设施和平台后端 Compose 编排。 +- `compose/`:基础设施、平台后端和平台前端 Compose 编排。 - `scripts/`:硬件与运行状态采集脚本。 - `benchmark/`:压测场景和单次运行元数据模板。 - `results/`:压测报告与不入库的原始数据。 diff --git a/compose/.env.example b/compose/.env.example index d787215..ab7bab7 100644 --- a/compose/.env.example +++ b/compose/.env.example @@ -35,6 +35,11 @@ BACKEND_MEMORY_LIMIT=4g BACKEND_CPU_LIMIT=2.0 BACKEND_UPLOADS_VOLUME_NAME=ai-soulmate-backend-uploads BACKEND_LOGS_VOLUME_NAME=ai-soulmate-backend-logs +FRONTEND_IMAGE=ai-soulmate-frontend:replace-with-source-commit +FRONTEND_BIND_ADDRESS=127.0.0.1 +FRONTEND_HOST_PORT=8080 +FRONTEND_MEMORY_LIMIT=1g +FRONTEND_CPU_LIMIT=1.0 APP_ENV=production SECRET_KEY=replace-with-a-random-value diff --git a/compose/README.md b/compose/README.md index 77b87d0..7b52092 100644 --- a/compose/README.md +++ b/compose/README.md @@ -1,6 +1,6 @@ # Compose 状态 -当前提交基础设施 POC 与平台后端:PostgreSQL、Redis、MinIO 和 FastAPI 后端。平台前端、管理端和网关仍在后续阶段。 +当前提交基础设施 POC 与平台应用:PostgreSQL、Redis、MinIO、FastAPI 后端和 Vue 平台前端。管理端和网关仍在后续阶段。 ## 运行基础设施 @@ -17,10 +17,14 @@ compose/.env 只放在服务器,已经被 .gitignore 忽略。生成后执行 按照 `docs/BACKEND-DEPLOYMENT.md` 生成后端密钥、创建 MinIO 应用账号、构建提交绑定的镜像并执行连接验收。 +## 运行平台前端 + +按照 `docs/FRONTEND-DEPLOYMENT.md` 构建提交绑定的前端镜像,并验证静态页面与同源后端代理。 + ## 当前门槛 - 平台后端仍需完成 MinIO 预签名上传、下载和浏览器 CORS 联调。 -- 平台前端仍需生成生产镜像并接入本地后端。 +- 平台前端仍需完成浏览器登录、预签名对象上传和主要页面联调。 - mlkj-admin 仍需实现 AI SoulMate-only 启动模式,避免初始化无关业务数据库和默认账号。 - nginx-server 的公网路由不能原样复用;完成业务镜像后再使用环境无关的网关模板或客户现有网关。 diff --git a/compose/docker-compose.backend.yml b/compose/docker-compose.backend.yml index 4b999d4..06a998f 100644 --- a/compose/docker-compose.backend.yml +++ b/compose/docker-compose.backend.yml @@ -62,6 +62,26 @@ services: networks: - internal + frontend: + image: ${FRONTEND_IMAGE:?FRONTEND_IMAGE is required} + restart: unless-stopped + ports: + - "${FRONTEND_BIND_ADDRESS:?FRONTEND_BIND_ADDRESS is required}:${FRONTEND_HOST_PORT:-8080}:8080" + depends_on: + backend: + condition: service_healthy + mem_limit: ${FRONTEND_MEMORY_LIMIT:-1g} + cpus: ${FRONTEND_CPU_LIMIT:-1.0} + security_opt: + - no-new-privileges:true + logging: + driver: json-file + options: + max-size: 10m + max-file: "3" + networks: + - internal + volumes: backend_uploads: name: ${BACKEND_UPLOADS_VOLUME_NAME:-ai-soulmate-backend-uploads} diff --git a/docs/DEPLOYMENT-RUNBOOK.md b/docs/DEPLOYMENT-RUNBOOK.md index cb07010..cf3cfc9 100644 --- a/docs/DEPLOYMENT-RUNBOOK.md +++ b/docs/DEPLOYMENT-RUNBOOK.md @@ -107,7 +107,7 @@ backup_directory="$(printf '%s\n' "$backup_output" | sed -n 's/^Infrastructure b ## 5. 业务部署门槛 -后端本地容器的配置、构建、启动和连接验收见 `docs/BACKEND-DEPLOYMENT.md`。后端先绑定回环地址,数据库和 Redis 不向局域网开放;MinIO API 只绑定批准的局域网地址,控制台保持回环绑定。 +后端本地容器的配置、构建、启动和连接验收见 `docs/BACKEND-DEPLOYMENT.md`,平台前端见 `docs/FRONTEND-DEPLOYMENT.md`。后端先绑定回环地址,数据库和 Redis 不向局域网开放;前端和 MinIO API 只绑定批准的局域网地址,MinIO 控制台保持回环绑定。 平台后端已有独立镜像、无源码挂载的 Compose、资源上限、日志轮换、健康检查和 MinIO provider。继续完成以下业务门槛: diff --git a/docs/FRONTEND-DEPLOYMENT.md b/docs/FRONTEND-DEPLOYMENT.md new file mode 100644 index 0000000..bfc1a50 --- /dev/null +++ b/docs/FRONTEND-DEPLOYMENT.md @@ -0,0 +1,30 @@ +# AI SoulMate 平台前端本地部署 + +平台前端使用多阶段镜像构建 Vue 静态资源,并由镜像内的 Nginx 提供页面。浏览器使用同源 `/api`、`/uploads` 和 `/ws` 路径,Nginx 在 Docker 内部网络中代理到 `backend:3000`,因此不会把用户电脑的 `localhost` 当成服务器。 + +## 构建镜像 + +```bash +cd /srv/ai-soulmate-local-deployment +./scripts/configure-backend-env.sh \ + compose/.env \ + /srv/ai-soulmate/sources/ai-soulmate-server \ + 192.168.3.102 + +./scripts/build-frontend-image.sh \ + compose/.env \ + /srv/ai-soulmate/sources/ai-soulmate-server +``` + +配置脚本将前端镜像标签绑定到源码提交,并把前端监听地址设为当前服务器的局域网地址。构建脚本拒绝错误分支、未提交的受跟踪文件和不匹配的镜像标签。 + +## 启动与验收 + +```bash +./scripts/start-frontend.sh compose/.env +./scripts/verify-frontend.sh compose/.env +``` + +验证脚本同时检查前端 `/health`、Vue 页面挂载点和经过前端 Nginx 代理的 `/api/health`,最后一项必须确认数据库为 `connected`。 + +当前 POC 地址为 `http://192.168.3.102:8080`。该地址只应用于受控局域网功能联调,不代表正式交付入口。正式交付应由统一网关提供 TLS,并为浏览器、管理端和农场工作站定义明确的访问策略。 diff --git a/scripts/build-frontend-image.sh b/scripts/build-frontend-image.sh new file mode 100755 index 0000000..d3ae1b4 --- /dev/null +++ b/scripts/build-frontend-image.sh @@ -0,0 +1,45 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +env_file="${1:-compose/.env}" +source_directory="${2:-/srv/ai-soulmate/sources/ai-soulmate-server}" + +for required_command in docker git sed; do + if ! command -v "$required_command" >/dev/null 2>&1; then + printf 'Required command is unavailable: %s\n' "$required_command" >&2 + exit 1 + fi +done +if [[ ! -r "$env_file" ]]; then + printf 'Environment file not found: %s\n' "$env_file" >&2 + exit 1 +fi +if [[ ! -r "$source_directory/frontend-vue/Dockerfile" ]]; then + printf 'Frontend Dockerfile not found under: %s\n' "$source_directory" >&2 + exit 1 +fi + +source_branch="$(git -C "$source_directory" branch --show-current)" +source_commit="$(git -C "$source_directory" rev-parse HEAD)" +source_short_commit="${source_commit:0:12}" +image="$(sed -n 's/^FRONTEND_IMAGE=//p' "$env_file" | head -n 1)" +if [[ "$source_branch" != "local-deployment" ]]; then + printf 'Expected source branch local-deployment, found: %s\n' "$source_branch" >&2 + exit 1 +fi +if [[ -n "$(git -C "$source_directory" status --short --untracked-files=no)" ]]; then + printf 'Tracked source changes are present; refusing to build an uncommitted image.\n' >&2 + exit 1 +fi +if [[ "$image" != "ai-soulmate-frontend:${source_short_commit}" ]]; then + printf 'FRONTEND_IMAGE does not match source commit; rerun configure-backend-env.sh.\n' >&2 + exit 1 +fi + +docker build \ + --label "org.opencontainers.image.revision=${source_commit}" \ + --tag "$image" \ + "$source_directory/frontend-vue" + +docker image inspect "$image" \ + --format 'Frontend image built: {{index .RepoTags 0}} id={{.Id}} size={{.Size}}' diff --git a/scripts/configure-backend-env.sh b/scripts/configure-backend-env.sh index e65c1b4..6da986c 100755 --- a/scripts/configure-backend-env.sh +++ b/scripts/configure-backend-env.sh @@ -81,6 +81,11 @@ set_value BACKEND_MEMORY_LIMIT 4g set_value BACKEND_CPU_LIMIT 2.0 set_value BACKEND_UPLOADS_VOLUME_NAME ai-soulmate-backend-uploads set_value BACKEND_LOGS_VOLUME_NAME ai-soulmate-backend-logs +set_value FRONTEND_IMAGE "ai-soulmate-frontend:${source_short_commit}" +set_value FRONTEND_BIND_ADDRESS "$public_host" +set_value FRONTEND_HOST_PORT 8080 +set_value FRONTEND_MEMORY_LIMIT 1g +set_value FRONTEND_CPU_LIMIT 1.0 set_value APP_ENV production ensure_secret SECRET_KEY diff --git a/scripts/create-local-env.sh b/scripts/create-local-env.sh index a131ef0..c3635b0 100755 --- a/scripts/create-local-env.sh +++ b/scripts/create-local-env.sh @@ -60,6 +60,11 @@ BACKEND_MEMORY_LIMIT=4g BACKEND_CPU_LIMIT=2.0 BACKEND_UPLOADS_VOLUME_NAME=ai-soulmate-backend-uploads BACKEND_LOGS_VOLUME_NAME=ai-soulmate-backend-logs +FRONTEND_IMAGE=ai-soulmate-frontend:local-deployment +FRONTEND_BIND_ADDRESS=127.0.0.1 +FRONTEND_HOST_PORT=8080 +FRONTEND_MEMORY_LIMIT=1g +FRONTEND_CPU_LIMIT=1.0 APP_ENV=production SECRET_KEY=$(random_secret) diff --git a/scripts/start-backend.sh b/scripts/start-backend.sh index 53d12cf..f59f4d5 100755 --- a/scripts/start-backend.sh +++ b/scripts/start-backend.sh @@ -33,5 +33,5 @@ compose_command=( -f "$compose_file" ) "${compose_command[@]}" config --quiet -"${compose_command[@]}" up -d +"${compose_command[@]}" up -d backend "${compose_command[@]}" ps --all diff --git a/scripts/start-frontend.sh b/scripts/start-frontend.sh new file mode 100755 index 0000000..a04cbbe --- /dev/null +++ b/scripts/start-frontend.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +env_file="${1:-compose/.env}" +compose_file="${BACKEND_COMPOSE_FILE:-compose/docker-compose.backend.yml}" + +if [[ ! -r "$env_file" ]]; then + printf 'Environment file not found: %s\n' "$env_file" >&2 + exit 1 +fi + +env_value() { + sed -n "s/^${1}=//p" "$env_file" | head -n 1 +} + +project_name="$(env_value BACKEND_COMPOSE_PROJECT_NAME)" +frontend_image="$(env_value FRONTEND_IMAGE)" +if [[ -z "$project_name" || "$project_name" == "$(env_value COMPOSE_PROJECT_NAME)" ]]; then + printf 'BACKEND_COMPOSE_PROJECT_NAME must be set and differ from the infrastructure project.\n' >&2 + exit 1 +fi +if [[ -z "$frontend_image" ]] || ! docker image inspect "$frontend_image" >/dev/null 2>&1; then + printf 'Configured frontend image is not available locally: %s\n' "$frontend_image" >&2 + exit 1 +fi + +compose_command=( + docker compose + --project-name "$project_name" + --env-file "$env_file" + -f "$compose_file" +) +"${compose_command[@]}" config --quiet +"${compose_command[@]}" up -d frontend +"${compose_command[@]}" ps --all diff --git a/scripts/verify-frontend.sh b/scripts/verify-frontend.sh new file mode 100755 index 0000000..d4da532 --- /dev/null +++ b/scripts/verify-frontend.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +env_file="${1:-compose/.env}" +compose_file="${BACKEND_COMPOSE_FILE:-compose/docker-compose.backend.yml}" + +for required_command in curl docker jq sed; do + if ! command -v "$required_command" >/dev/null 2>&1; then + printf 'Required command is unavailable: %s\n' "$required_command" >&2 + exit 1 + fi +done +if [[ ! -r "$env_file" ]]; then + printf 'Environment file not found: %s\n' "$env_file" >&2 + exit 1 +fi + +env_value() { + sed -n "s/^${1}=//p" "$env_file" | head -n 1 +} + +project_name="$(env_value BACKEND_COMPOSE_PROJECT_NAME)" +frontend_bind_address="$(env_value FRONTEND_BIND_ADDRESS)" +frontend_host_port="$(env_value FRONTEND_HOST_PORT)" +if [[ -z "$project_name" || "$project_name" == "$(env_value COMPOSE_PROJECT_NAME)" ]]; then + printf 'BACKEND_COMPOSE_PROJECT_NAME must be set and differ from the infrastructure project.\n' >&2 + exit 1 +fi +compose_command=( + docker compose + --project-name "$project_name" + --env-file "$env_file" + -f "$compose_file" +) +"${compose_command[@]}" config --quiet + +base_url="http://${frontend_bind_address}:${frontend_host_port}" +api_json="" +for _attempt in $(seq 1 18); do + if curl --fail --silent --show-error --max-time 5 "${base_url}/health" | grep -q '^ok'; then + if api_json="$(curl --fail --silent --show-error --max-time 5 "${base_url}/api/health" 2>/dev/null)"; then + if printf '%s' "$api_json" | jq -e '.status == "healthy" and .database == "connected"' >/dev/null; then + break + fi + fi + fi + api_json="" + sleep 5 +done +if [[ -z "$api_json" ]]; then + printf 'Frontend or proxied API health check did not become healthy: %s\n' "$base_url" >&2 + "${compose_command[@]}" ps >&2 + exit 1 +fi + +index_html="$(curl --fail --silent --show-error --max-time 5 "${base_url}/")" +if ! printf '%s' "$index_html" | grep -q 'id="app"'; then + printf 'Frontend index does not contain the Vue application mount point.\n' >&2 + exit 1 +fi + +printf '%s\n' "$api_json" | jq . +"${compose_command[@]}" ps +printf 'Frontend static site and proxied backend health checks passed.\n'