Разработана первая версия приложений

2026-07-10 18:06:14 +03:00
parent aa8761d1b3
commit 8c7b4074c4
162 changed files with 12178 additions and 16 deletions
@@ -0,0 +1,207 @@
+# HAN Chat production-like deployment runbook
+
+This is the executable checklist for the single-VM contour. PostgreSQL and S3
+are managed external services. Never use `docker compose down -v`, an Alembic
+downgrade, or a mutable image tag during deployment.
+
+## Gate 0 — decisions and ownership
+
+- [ ] Release SHA/digests, maintenance window, on-call and rollback owner recorded.
+- [ ] RPO/RTO accepted; initial targets are PG RPO <=15 minutes and RTO <=4 hours.
+- [ ] Remote OTLP backend selected, or debug-only acceptance limitation accepted.
+- [ ] Mock OTP, Safety stub and bitrix-sync stub risks explicitly accepted.
+
+## Gate 1 — VPC, DNS and security groups
+
+- [ ] Managed PostgreSQL has only a private endpoint and accepts traffic from VM SG.
+- [ ] Internet can reach only VM TCP 80/443; SSH is restricted to VPN/ops CIDR.
+- [ ] Ports 6379, 4317/4318, 8000, 8080 and 9000 are denied externally.
+- [ ] DNS `A` for `PUBLIC_HOST` points at the VM and outbound HTTPS is available.
+
+## Gate 2 — VM hardening
+
+- [ ] Ubuntu 24.04, NTP, unattended security updates and disk alerts are active.
+- [ ] Key-only deploy account works in a second session; root/password SSH is off.
+- [ ] UFW/cloud SG and `DOCKER-USER` policy survive reboot.
+- [ ] Docker Engine and Compose support `include` and long-form `env_file`.
+
+## Gate 3 — managed PostgreSQL
+
+- [ ] Daily backup, PITR, deletion protection, encryption and alerts are enabled.
+- [ ] Provider CA is installed at `PG_CA_HOST_PATH`; all DSNs use `verify-full`.
+- [ ] Schemas `han_app`, `bitrix_local`, `bitrix_sync`, `message_safety`, `keycloak`
+      have separate migration/runtime roles with tested negative grants.
+- [ ] Migration tested against an empty DB and a clone of the previous release.
+
+## Gate 4 — Selectel S3
+
+- [ ] Quarantine, attachments and documents buckets are private and encrypted.
+- [ ] API credentials are prefix-scoped; Safety credentials are quarantine read-only.
+- [ ] Browser CORS permits exact HTTPS origin and PUT headers only.
+- [ ] Quarantine lifecycle exceeds Safety poll/recovery; data retention is approved.
+
+## Gate 5 — immutable release
+
+- [ ] Checkout is detached at the approved SHA and working tree is clean.
+- [ ] Service images are immutable and scanned; no unresolved critical/high issue.
+- [ ] Root `docker-compose.yml` is the only deployment entry point.
+
+## Gate 6 — environment and secrets
+
+```sh
+umask 077
+cp .env.example .env
+chmod 600 .env
+# Replace placeholders using a protected editor/secret manager.
+./scripts/validate-env .env
+docker compose --env-file .env config --quiet
+```
+
+- [ ] Token pairs match, PG verifies TLS, public URLs are HTTPS.
+- [ ] Mock OTP risk is accepted and all secrets are unique >=128-bit values.
+- [ ] `FRONTEND_DEV_PROXY_ENABLED=false` and Safety/nginx timeout budgets match.
+
+## Gate 7 — images and static frontend
+
+```sh
+docker compose --env-file .env pull
+docker compose --env-file .env build --pull frontend-static nginx redis
+docker compose --env-file .env run --rm frontend-static
+```
+
+- [ ] Frontend export was tested/scanned and copied by `frontend-static` into its named volume.
+- [ ] Build artifacts contain no secrets or unintended source maps.
+- [ ] At least 30% VM disk remains free.
+
+## Gate 8 — topology
+
+```sh
+docker compose --env-file .env config --services
+python3 -m unittest discover -s tests -v
+```
+
+- [ ] Exactly nginx publishes `80:80` and `443:443`; no PostgreSQL service exists.
+- [ ] Redis AOF/RDB/ACL and OTEL persistent queue volumes are present.
+- [ ] `backend` and `observability` are internal networks.
+
+## Gate 9 — ACME/TLS bootstrap
+
+Set `NGINX_TLS_ENABLED=false` only for this bootstrap command:
+
+```sh
+NGINX_TLS_ENABLED=false docker compose --env-file .env up -d nginx
+docker compose --profile certbot run --rm certbot certonly \
+  --webroot -w /var/www/certbot -d "$PUBLIC_HOST" \
+  --cert-name "$PUBLIC_HOST" --email "$ACME_EMAIL" \
+  --agree-tos --no-eff-email --non-interactive
+docker compose --env-file .env up -d --force-recreate nginx
+docker compose exec -T nginx nginx -t -c /tmp/nginx.conf
+```
+
+First rehearse with Certbot `--staging`. Install a twice-daily systemd timer for
+`deployment/scripts/ssl-renew.sh`; test `certbot renew --dry-run`. Enable HSTS
+only after chain, hostname, redirect and TLS 1.2/1.3 checks pass.
+
+## Gate 10 — migrations and seed
+
+Create a provider PITR marker, then:
+
+```sh
+PITR_MARKER_CONFIRMED=true deployment/scripts/migrate.sh
+deployment/scripts/seed.sh
+```
+
+- [ ] Expected Alembic revisions are active and runtime users did not perform DDL.
+- [ ] Seed succeeds twice and mandatory settings contain no secret.
+- [ ] Schema remains backward-compatible with the previous images.
+
+## Gate 11 — Keycloak
+
+```sh
+docker compose up -d keycloak
+docker compose ps keycloak
+```
+
+- [ ] Discovery/JWKS issuer is the exact public `/auth` HTTPS URL.
+- [ ] Frontend client is public PKCE S256; implicit/password/social flows are off.
+- [ ] Wrong/replayed OTP and limits fail safely; settings bridge is fail-closed.
+- [ ] Bootstrap admin was removed/rotated and named admin MFA is enabled.
+
+## Gate 12 — ordered startup and readiness
+
+```sh
+docker compose up -d redis
+docker compose up -d keycloak otel-collector
+docker compose up -d message-safety
+docker compose up -d api-backend
+docker compose up -d bitrix-local-app bitrix-sync
+docker compose up -d nginx
+docker compose ps
+```
+
+- [ ] No restart loop/OOM; critical readiness is green.
+- [ ] Only documented Bitrix not-installed/sync-stub degradation remains.
+- [ ] External `/internal/*` is 404 and OTEL accepts telemetry.
+
+## Gate 13 — Bitrix24
+
+- [ ] Install, handler and placement URLs use the exact public HTTPS paths.
+- [ ] Connector `han_mobile_app` is active on Open Line 8; events are bound once.
+- [ ] OAuth is encrypted; callback/application/service tokens never enter logs.
+- [ ] Outbound and operator reply paths are idempotent; internal status is private.
+
+## Gate 14 — smoke and E2E
+
+```sh
+deployment/scripts/smoke.sh
+```
+
+- [ ] Guest, OTP/PKCE/bootstrap/session, refresh and logout paths pass.
+- [ ] Safety allow/deny/pending/timeout and one concurrent slow poll pass.
+- [ ] File quarantine/promote/delete, owner-only download and audit pass.
+- [ ] WS reconnect plus REST reconciliation, ownership 404, idempotency and 429 pass.
+- [ ] Logs contain no PII, message body, token or presigned query.
+
+## Gate 15 — observability
+
+- [ ] Known request ID links nginx, API and downstream trace; UX ID is not a label.
+- [ ] Three signals reach the selected backend; SLO queries and alerts are tested.
+- [ ] Remote outage fills/drains the bounded persistent queue without business outage.
+- [ ] Secret/PII canary is absent. Collector restart/drop/refused metrics are checked.
+
+For local acceptance only, start the redacted debug collector with:
+`docker compose --profile observability-local up -d otel-collector-local`.
+
+## Gate 16 — open traffic
+
+- [ ] Gates 0–15 are signed; fresh backup/PITR evidence and previous images exist.
+- [ ] HSTS is enabled, release digests/schema/realm versions are recorded.
+- [ ] No active page; on-call and product owner accept stub limitations.
+- [ ] Observe 5xx/auth/delivery/DB/Redis/OOM/OTEL queue/Bitrix for 60 minutes.
+
+## Backup and restore
+
+Provider backup/PITR is authoritative. A supplemental verified logical dump:
+
+```sh
+PG_BACKUP_DSN='postgresql://...?...sslmode=verify-full&sslrootcert=...' \
+  deployment/scripts/backup.sh /opt/han-chat/backups
+```
+
+Quarterly, restore PG and S3 into an isolated VPC, deploy the same image digests,
+do not route production DNS/Bitrix callbacks, run smoke, and record measured RPO/RTO.
+Redis may be restored empty; its AOF/RDB is not a business backup.
+
+## Rollback
+
+Only roll back to images compatible with the current schema:
+
+```sh
+SCHEMA_BACKWARD_COMPATIBLE_CONFIRMED=true \
+  deployment/scripts/rollback.sh /secure/path/previous-release.env
+ENV_FILE=/secure/path/previous-release.env deployment/scripts/smoke.sh
+```
+
+Never run Alembic downgrade. After a backward-incompatible migration choose a
+forward fix or coordinated PITR/S3/Bitrix reconciliation under maintenance.
+Always verify outbox/inbox/recovery so an ambiguous message is not sent twice.
@@ -0,0 +1,31 @@
+schema_version: 1
+settings:
+  auth.phone.enabled: {type: boolean, value: true, public: true}
+  auth.password.enabled: {type: boolean, value: false, public: true}
+  otp.phone.max_send_attempts_per_24h: {type: integer, value: 3, public: false}
+  otp.phone.min_seconds_between_attempts: {type: integer, value: 30, public: false}
+  operator.call.phone: {type: string, value: "+74999591007", public: true}
+  consent.personal_data.required: {type: boolean, value: true, public: true}
+  consent.personal_data.document_url: {type: string, value: "https://www.han0107.ru/privacy/persdata-agree-mobile", public: true}
+  consent.personal_data.version: {type: string, value: "2026-06-10", public: true}
+  consent.user_agreement.required: {type: boolean, value: true, public: true}
+  consent.user_agreement.document_url: {type: string, value: "https://www.han0107.ru/user-agreement", public: true}
+  consent.user_agreement.version: {type: string, value: "2026-06-10", public: true}
+  consent.marketing.required: {type: boolean, value: false, public: true}
+  consent.marketing.version: {type: string, value: "2026-06-10", public: true}
+  chat.attachments.allowed_extensions: {type: string_list, value: "jpg,jpeg,png,webp,heic,heif,pdf", public: true}
+  chat.attachments.allowed_mime_types: {type: string_list, value: "image/jpeg,image/png,image/webp,image/heic,image/heif,application/pdf", public: true}
+  chat.attachments.disallowed_extensions: {type: string_list, value: "svg,doc,docx,xls,xlsx,csv", public: false}
+  chat.attachments.max_size_mb: {type: integer, value: 5, public: true}
+  chat.attachments.storage: {type: string, value: selectel_s3, public: false}
+  chat.attachments.upload_mode: {type: string, value: presigned_put, public: false}
+  chat.attachments.safety_scan_required: {type: boolean, value: true, public: false}
+  chat.attachments.presigned_upload_ttl_seconds: {type: integer, value: 600, public: true}
+  rate_limit.message_send.per_user: {type: string, value: "30/minute", public: true}
+  rate_limit.message_send.per_dialog: {type: string, value: "20/minute", public: false}
+  rate_limit.download_url.per_user: {type: string, value: "60/hour", public: false}
+  rate_limit.public_endpoints.per_ip: {type: string, value: "60/minute", public: true}
+  rate_limit.login.per_ip: {type: string, value: "10/minute", public: true}
+  ux.session.idle_timeout_minutes: {type: integer, value: 30, public: true}
+  security.cors.allowed_origins: {type: string_list, value: "https://chat.example.ru", public: false}
+  security.public_cache.max_age_seconds: {type: integer, value: 3600, public: false}
@@ -0,0 +1,72 @@
+services:
+  migrate-api:
+    image: ${API_BACKEND_IMAGE:-han-chat-api-backend:local}
+    profiles: ["ops"]
+    env_file:
+      - path: ../.env
+        required: false
+    entrypoint: []
+    command: ["alembic", "upgrade", "head"]
+    volumes:
+      - ${PG_CA_HOST_PATH}:/run/secrets/pg-ca.pem:ro
+    networks: [backend]
+    restart: "no"
+    security_opt: ["no-new-privileges:true"]
+
+  migrate-bitrix-local:
+    image: ${BITRIX_LOCAL_APP_IMAGE:-han-chat-bitrix-local-app:local}
+    profiles: ["ops"]
+    env_file:
+      - path: ../.env
+        required: false
+    entrypoint: []
+    command: ["alembic", "upgrade", "head"]
+    volumes:
+      - ${PG_CA_HOST_PATH}:/run/secrets/pg-ca.pem:ro
+    networks: [backend]
+    restart: "no"
+    security_opt: ["no-new-privileges:true"]
+
+  migrate-bitrix-sync:
+    image: ${BITRIX_SYNC_IMAGE:-han-chat-bitrix-sync:local}
+    profiles: ["ops"]
+    env_file:
+      - path: ../.env
+        required: false
+    entrypoint: []
+    command: ["alembic", "upgrade", "head"]
+    volumes:
+      - ${PG_CA_HOST_PATH}:/run/secrets/pg-ca.pem:ro
+    networks: [backend]
+    restart: "no"
+    security_opt: ["no-new-privileges:true"]
+
+  seed-settings:
+    image: ${API_BACKEND_IMAGE:-han-chat-api-backend:local}
+    profiles: ["ops"]
+    env_file:
+      - path: ../.env
+        required: false
+    entrypoint: []
+    command:
+      - /bin/sh
+      - -ec
+      - >-
+        python -m app.cli.seed_settings
+        --file /deployment/app-settings.production-like.yaml
+        && python -m app.cli.validate_settings
+    volumes:
+      - ${PG_CA_HOST_PATH}:/run/secrets/pg-ca.pem:ro
+      - ./app-settings.production-like.yaml:/deployment/app-settings.production-like.yaml:ro
+    networks: [backend]
+    restart: "no"
+    security_opt: ["no-new-privileges:true"]
+
+  toolbox:
+    image: curlimages/curl:8.11.1
+    profiles: ["ops"]
+    entrypoint: ["sleep", "infinity"]
+    networks: [backend, observability]
+    restart: "no"
+    cap_drop: ["ALL"]
+    security_opt: ["no-new-privileges:true"]
@@ -0,0 +1,24 @@
+#!/bin/sh
+set -eu
+
+if [ -z "${PG_BACKUP_DSN:-}" ]; then
+  echo "PG_BACKUP_DSN is required (managed PostgreSQL TLS DSN, supplied via secure environment)." >&2
+  exit 64
+fi
+case "$PG_BACKUP_DSN" in
+  *sslmode=verify-full*sslrootcert=*) ;;
+  *) echo "PG_BACKUP_DSN must enforce sslmode=verify-full and sslrootcert." >&2; exit 64 ;;
+esac
+
+output_dir=${1:-/opt/han-chat/backups}
+umask 077
+mkdir -p "$output_dir"
+stamp=$(date -u +%Y%m%dT%H%M%SZ)
+archive="$output_dir/han-chat-$stamp.dump"
+
+pg_dump --dbname="$PG_BACKUP_DSN" --format=custom --no-owner --no-privileges --file="$archive"
+pg_restore --list "$archive" >/dev/null
+sha256sum "$archive" > "$archive.sha256"
+chmod 600 "$archive" "$archive.sha256"
+echo "Logical backup verified: $archive"
+echo "This supplements, but does not replace, provider backup/PITR and restore rehearsal."
@@ -0,0 +1,18 @@
+#!/bin/sh
+set -eu
+cd "$(dirname "$0")/../.."
+
+if [ "${PITR_MARKER_CONFIRMED:-false}" != "true" ]; then
+  echo "Refusing migration: create provider PITR marker, then set PITR_MARKER_CONFIRMED=true" >&2
+  exit 64
+fi
+
+./scripts/validate-env "${ENV_FILE:-.env}"
+docker compose --env-file "${ENV_FILE:-.env}" config --quiet
+docker compose --env-file "${ENV_FILE:-.env}" --profile ops run --rm migrate-api alembic current
+docker compose --env-file "${ENV_FILE:-.env}" --profile ops run --rm migrate-bitrix-local alembic current
+docker compose --env-file "${ENV_FILE:-.env}" --profile ops run --rm migrate-bitrix-sync alembic current
+docker compose --env-file "${ENV_FILE:-.env}" --profile ops run --rm migrate-api
+docker compose --env-file "${ENV_FILE:-.env}" --profile ops run --rm migrate-bitrix-local
+docker compose --env-file "${ENV_FILE:-.env}" --profile ops run --rm migrate-bitrix-sync
+echo "Migrations completed; record revisions in release evidence."
@@ -0,0 +1,21 @@
+#!/bin/sh
+set -eu
+cd "$(dirname "$0")/../.."
+
+previous_env=${1:-}
+if [ -z "$previous_env" ] || [ ! -r "$previous_env" ]; then
+  echo "Usage: $0 /secure/path/previous-release.env" >&2
+  exit 64
+fi
+if [ "${SCHEMA_BACKWARD_COMPATIBLE_CONFIRMED:-false}" != "true" ]; then
+  echo "Refusing rollback: set SCHEMA_BACKWARD_COMPATIBLE_CONFIRMED=true after migration review." >&2
+  exit 64
+fi
+
+./scripts/validate-env "$previous_env"
+docker compose --env-file "$previous_env" config --quiet
+docker compose --env-file "$previous_env" up -d --remove-orphans
+docker compose --env-file "$previous_env" ps
+
+echo "Application images rolled back without Alembic downgrade."
+echo "Run deployment/scripts/smoke.sh with ENV_FILE=$previous_env and verify outbox/inbox idempotency."
@@ -0,0 +1,7 @@
+#!/bin/sh
+set -eu
+cd "$(dirname "$0")/../.."
+
+./scripts/validate-env "${ENV_FILE:-.env}"
+docker compose --env-file "${ENV_FILE:-.env}" --profile ops run --rm seed-settings
+echo "Seed and mandatory-settings validation completed."
@@ -0,0 +1,30 @@
+#!/bin/sh
+set -eu
+cd "$(dirname "$0")/../.."
+
+ENV_FILE=${ENV_FILE:-.env}
+./scripts/validate-env "$ENV_FILE"
+set -a
+. "./$ENV_FILE"
+set +a
+
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+http_code=$(curl -sS -o /dev/null -w '%{http_code}' "http://${PUBLIC_HOST}/")
+[ "$http_code" = "308" ] || { echo "Expected HTTP 308, got $http_code" >&2; exit 1; }
+curl -fsS "${PUBLIC_WEB_URL}/api/v1/public/app-config" -o "$tmp/app-config.json"
+curl -fsS "${PUBLIC_WEB_URL}/api/v1/public/content" -o "$tmp/content.json"
+curl -fsS "${PUBLIC_WEB_URL}/auth/realms/${KEYCLOAK_REALM}/.well-known/openid-configuration" -o "$tmp/oidc.json"
+
+internal_code=$(curl -sS -o /dev/null -w '%{http_code}' "${PUBLIC_WEB_URL}/internal/safety/v1/messages/check")
+[ "$internal_code" = "404" ] || { echo "Public /internal returned $internal_code, expected 404" >&2; exit 1; }
+
+headers=$(curl -fsSI "${PUBLIC_WEB_URL}/")
+printf '%s' "$headers" | grep -qi '^x-content-type-options: nosniff'
+printf '%s' "$headers" | grep -qi '^x-request-id:'
+printf '%s' "$headers" | grep -qi '^content-security-policy:'
+
+openssl s_client -connect "${PUBLIC_HOST}:443" -servername "$PUBLIC_HOST" </dev/null 2>/dev/null \
+  | openssl x509 -noout -checkend 604800
+echo "Public edge smoke passed."
@@ -0,0 +1,13 @@
+#!/bin/sh
+set -eu
+cd "$(dirname "$0")/../.."
+
+lock=/tmp/han-chat-cert-renew.lock
+exec 9>"$lock"
+flock -n 9 || { echo '{"event":"tls.renew.skipped","reason":"lock_busy"}'; exit 0; }
+
+docker compose --profile certbot run --rm certbot renew \
+  --webroot -w /var/www/certbot --quiet
+docker compose exec -T nginx nginx -t -c /tmp/nginx.conf
+docker compose exec -T nginx nginx -s reload
+echo "{\"event\":\"tls.renew.completed\",\"timestamp\":\"$(date -u +%FT%TZ)\"}"