Visura API 部署指南：Docker Compose 编排、健康检查与日志卷调优完整实战

【免费下载链接】visura-apiServizio API per lestrazione automatizzata di dati catastali dal portale SISTER项目地址https://gitcode.com/gh_mirrors/vi/visura-api点击查看免费下载本文是 Visura API 的部署指南教你用 Docker Compose 一键编排这个基于 FastAPI Playwright 的意大利地籍数据自动抓取服务对接 SISTER 门户网站并掌握健康检查Health Check与日志卷挂载的调优技巧。⚠️法律提示使用本服务前须先在 Agenzia delle Entrate 的 Area Personale 中注册并开通 SISTER 服务。自动化访问可能违反门户条款责任由使用者自行承担详见 README.md 中的免责声明。一、部署前准备环境与账号清单在动手之前先确认以下条件全部就绪准备项要求说明️ 操作系统Linux / macOS / WindowsWSL2官方镜像基于python:3.11-slim Docker Engine20.0提供容器运行环境 Docker Composev2负责编排与docker compose命令 SPID 凭据Sielte ID / PosteID登录时需手机 App 批准推送通知 SISTER 账号已开通 SISTER 服务没有此账号一切无从谈起服务启动后的完整链路是FastAPI 接收 HTTP 请求 → 内部队列串行调度 → Playwright 驱动 Chromium 无头浏览器访问 SISTER 门户 → 轮询接口返回结果。理解了这条链路后面解释健康检查为何要等待 120 秒就容易多了。二、Docker Compose 编排最快 3 步部署方法1. 获取代码并配置 .envgit clone https://gitcode.com/gh_mirrors/vi/visura-api cd visura-api cp .env.example .env # 编辑 .env填入你的 SPID 凭据ADE_USERNAME / ADE_PASSWORD.env.example 已内置全部可调参数及中文注释复制后只需修改凭据相关项即可。2. 构建并启动docker compose up -d首次执行会先构建镜像Dockerfile 基于python:3.11-slim预装了 Chromium 运行所需的全部系统库libnss3、libatk、xvfb等创建非 root 用户appuser并在该用户下执行playwright install chromiumEXPOSE 8000后以单 worker 的 uvicorn 启动。为什么必须用提供的 DockerfileChromium 在裸容器里极易因缺失系统库而崩溃。官方镜像已解决这类问题包括移除了与 Docker 不兼容的--single-process参数见 CHANGELOG.md 中Docker 稳定性条目。3. 验证部署成功curl http://localhost:8000/health首次启动时服务会依次完成启动无头浏览器 → SPID 登录请在 120 秒内到手机 App 上批准推送通知→ 进入 SISTER 的 Visure catastali 页面 → 启动 keep-alive 与队列 worker → 开始监听 8000 端口。三、docker-compose.yaml 关键配置逐项解读docker-compose.yaml 不到 30 行却覆盖了生产部署的四个核心点逐项拆解如下services: visure-service: build: . ports: - 8000:8000 # 宿主机 → 容器端口映射 env_file: - .env # 自动加载 SPID 凭据与调优参数 volumes: - ./logs:/app/logs:rw # 日志卷宿主机 logs 目录挂载进容器 restart: unless-stopped # 异常退出后自动拉起四个配置点分别解决什么问题env_file: .env—— 凭据不写死在编排文件里main.py启动时通过python-dotenv加载天然支持多环境切换./logs:/app/logs—— 容器是用完即毁的日志不落盘就会随容器消失。挂载后visura.log与页面 HTML 日志都持久化在宿主机上这是第五节调优的基础restart: unless-stopped—— 会话异常、内存波动等场景下自动恢复无需人工值守healthcheck—— 见下一节详解。另外stdin_open: true与tty: true是方便调试的配置注释中已建议生产环境移除。四、健康检查调优healthcheck 与 /health 端点Compose 层为什么 start_period 是 120 秒healthcheck: test: - CMD - python - -c - import urllib.request,sys;\nrurllib.request.urlopen(http://localhost:8000/health,timeout5);\nsys.exit(0 if r.status200 else 1) interval: 30s timeout: 10s retries: 3 start_period: 120s四个参数各有讲究参数值调优逻辑testPython 的urllib镜像里没有安装 curl而 Python 永远可用所以用标准库发 GET 请求/health返回 200 才算通过interval: 30s探测频率与浏览器 keep-alive 的 30 秒节奏呼应足够及时又不过度消耗retries: 3重试次数偶发超时不至于误判为不健康start_period: 120s启动宽限期⭐ 关键SPID 登录需等待 App 批准推送最长 120 秒期间/health未就绪是正常现象不能计入失败查看健康状态docker compose ps # 查看 STATUS 列的 (healthy) 标记 docker compose logs -f # 实时跟踪日志应用层/health 端点返回什么端点实现在 main.py返回三个字段{ status: healthy, authenticated: true, queue_size: 0 }authenticatedSISTER 会话是否有效。若为false说明登录未完成推送未批准或会话丢失服务会先尝试免 SPID 恢复、失败后自动重新登录逻辑见 main.py 的_ensure_authenticatedqueue_size积压请求数。请求在单一浏览器中串行执行该值持续增大说明消费速度跟不上可结合 tests/test_main.py 中的health_check单测理解其测试口径。调优建议把curl http://localhost:8000/health接入你自己的监控Prometheus blackbox、UptimeRobot 均可重点盯authenticated字段——HTTP 200 不代表会话一定活着业务可用性要以它为准。五、日志卷调优挂载、分级与隐私红线两级日志体系服务产生两类日志全部写入/app/logs即宿主机./logs类型位置内容价值文本日志logs/visura.log登录、导航、提取、错误的完整流程排障第一入口页面 HTML 日志logs/pages/session_id/浏览器访问过的每一页快照含 URL、步骤、时间戳元数据复现问题现场浏览器到底看到了什么HTML 快照由 utils.py 中的PageLogger类生成按login/、visura/、recovery/等流程分目录编号存储01_goto_login.html、02_...。生产环境必做的 3 个调优动作1️⃣ 关闭页面快照显著提速在.env中确认LOG_PAGES0该开关默认开启向后兼容生产关闭后每笔查询可省约 0.5–2 秒延迟参数说明见 .env.example 第 64–67 行。需要调试时再临时改回1。2️⃣ 按需切换日志级别LOG_LEVELINFO # 日常 LOG_LEVELDEBUG # 排障时开启输出更细文本日志同时输出到 stdout可被docker compose logs捕获和visura.log文件级别逻辑见 main.py。3️⃣ 配置快照目录与磁盘保护PAGES_LOG_DIR./logs/pages # 可改到独立数据盘避免挤占系统盘PageLogger有降级保护目录不可写时自动回落到/tmp/visura-api/logs/pages再失败则静默禁用页面日志主流程不受影响见 CHANGELOG.md PageLogger 健壮性条目。⚠️ 隐私红线务必阅读页面 HTML 快照中包含税号codice fiscale、产权人姓名、地址等个人数据logs/目录已被.gitignore排除严禁提交这些文件对外分享 issue、工单前先删除或匿名化 HTML 文件对logs/卷及备份应用与个人数据同级的访问控制并制定明确的留存删除策略。官方完整的操作建议见 README.md 的Protezione dati e retention章节。六、进阶调优用 .env 旋钮控制队列与内存除日志外.env.example 还暴露了若干直接影响稳定性的参数核心逻辑见 main.py 的VisuraService变量默认值作用与调优思路MAX_QUEUE_SIZE200队列上限超限返回 HTTP 429。客户端多、任务重时可上调但注意消费是串行的RESPONSE_TTL_SECONDS3600结果在内存中保留 1 小时防止长时间轮询导致的内存泄漏。客户端消费快可下调省内存RESPONSE_STORE_MAXSIZE10000结果缓存条数硬上限超出按 LRU 淘汰LOGIN_MAX_ATTEMPTS3SPID 推送未及时批准时的登录重试次数每次重试都会重新推送通知RESOURCE_BLOCK1拦截门户的图片/字体/媒体资源每请求省约 1–2 秒怀疑选择器失效时置0排查DROPDOWN_CACHE1缓存省份/市下拉框省 600–1800ms浏览器初始化后自动失效重建API_KEY无设置后业务接口需带X-API-Key请求头POST /shutdown等管理端点必须配置该变量才可用见 main.py组合调优示例面向多客户端的生产部署可参考——MAX_QUEUE_SIZE500、RESPONSE_TTL_SECONDS1800、LOG_PAGES0、API_KEY随机串、LOG_LEVELINFO。七、常见部署问题排查清单症状可能原因解决方法容器反复重启健康检查卡在startingSPID 推送 120 秒内未批准到手机 App 批准推送确认ADE_USERNAME/ADE_PASSWORD正确/health返回authenticated: false登录未成功或会话被踢查看docker compose logs -f服务会自动尝试 recovery → 重新登录请求返回 HTTP 429队列超过MAX_QUEUE_SIZE调大MAX_QUEUE_SIZE或降低客户端并发提交频率Chromium 在 Docker 内无法启动自行构建镜像缺少系统库改用仓库提供的 Dockerfile 构建logs/pages/为空目录权限不足或LOG_PAGES0检查PAGES_LOG_DIR权限调试时改为LOG_PAGES1门户提示Utente già in sessione上次会话未正常退出等待几分钟或到门户手动退出正常关闭容器时服务会先执行优雅登出graceful shutdown排查疑难问题时最有力的工具是logs/pages/里的 HTML 快照——它能精确还原浏览器在每个步骤看到的页面目录结构示例见 README.md 的 Logging e debug 章节。八、平滑下线与安全收尾优雅停止docker compose down触发SIGTERM服务会先在 SISTER 门户点击退出、再关闭浏览器避免残留会话API 方式停机配置API_KEY后可调用POST /shutdown适合纳入运维脚本合规提醒项目采用AGPL-3.0许可若 fork 后对外提供网络服务需履行 AGPL §13 的开源义务商用场景可参考 COMMERCIAL-LICENSE.md。总结一张清单回顾部署要点✅ 用仓库自带 Dockerfile 构建别自己拼装 Chromium 依赖 ✅ docker-compose.yaml 已内置restarthealthcheckstart_period: 120s对应 SPID 审批耗时勿随意调小 ✅ 监控以/health的authenticated字段为准而非仅看 HTTP 200 ✅ 生产环境设LOG_PAGES0提速LOG_LEVELINFO保留排障线索 ✅logs/卷包含个人数据严格控权、定期清理、永不入库 ✅ 配置API_KEY保护接口MAX_QUEUE_SIZE按客户端规模设定按本文步骤操作Visura API 即可在 3 条命令内完成容器化部署并通过健康检查与日志卷的组合调优获得一个可监控、可审计、可长期运行的地籍数据 API 服务。赞分享【免费下载链接】visura-apiServizio API per lestrazione automatizzata di dati catastali dal portale SISTER项目地址https://gitcode.com/gh_mirrors/vi/visura-api点击查看免费下载相关推荐使用 Docker 与 Docker Compose 部署 Mercure Hub镜像运行、健康检查与无根部署完整指南使用 Docker 与 Docker Compose 部署 Mercure Hub镜像运行、健康检查与无根部署完整指南 Mercure.rocks Hub 是后端即时通讯Kener v4 生产部署完整指南Docker Compose、预构建镜像与健康检查Kener v4 生产部署完整指南Docker Compose、预构建镜像与健康检查 本文基于 Kener v4 官方部署文档deployment.md/d可观测性后端前端运维git-pr-release常见问题解决7个常见错误及其修复方法git pr release常见问题解决7个常见错误及其修复方法 git pr release是一款高效的Release pull request生成工具能开发工具上一篇Meshroom 3D重建指南用节点式可视化编程把照片变成三维模型下一篇深入解读 curl INTERNALSlibcurl 内部架构、核心数据结构与移植性设计附 KBEngine 集成实例创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考