Ansible自动化部署静态网站：Ubuntu 20.04 + Nginx最佳实践

1. 项目概述：为什么用 Ansible 部署一个静态 HTML 网站，值得花一整个下午认真做一遍

你手头有个写好的个人作品集页面，或者公司产品页的纯 HTML 原型，甚至只是一页带 CSS 和 JS 的宣传单页——它不连数据库、不跑后端逻辑、不调 API，就靠浏览器原生渲染。你把它丢进index.html，本地双击能打开，但你想让它真正在公网被访问，还得上服务器。这时候，很多人会直接 SSH 登上去，手动装 Nginx，mkdir -p /var/www/mysite，cp -r ./dist/* /var/www/mysite/，再改/etc/nginx/sites-available/default，最后systemctl restart nginx。做完？是能跑，但下次换服务器、加新页面、更新文案、同步到测试环境……你还想再敲一遍这串命令吗？我试过三次，第三次改错了一个斜杠，导致整个站点 403，查了 47 分钟权限和 SELinux 上下文，才想起 Ubuntu 20.04 默认没开 SELinux——纯属手抖。

这就是 Ansible 进场的真实场景：它不解决“能不能跑”的问题，它解决的是“能不能每次都不出错、不漏步骤、不依赖记忆、不靠运气”的问题。Ansible 不是魔法，它是把人脑里那套“先装什么、再配什么、最后测什么”的操作流程，翻译成机器可读、可验证、可回滚的 YAML 清单。Ubuntu 20.04 是这个流程最稳的底座——LTS 版本、内核稳定、包管理成熟、Nginx 版本（1.18.0）对静态资源缓存、Gzip 压缩、MIME 类型识别都已打磨多年；Nginx 是这个场景最轻快的引擎——没有 Apache 那堆模块加载开销，没有 Node.js 那个进程管理复杂度，它就是为“把文件高效地扔给浏览器”而生的；HTML 静态网站本身，则是整个链条里最干净的输入源——没有版本冲突、没有运行时依赖、没有热更新陷阱。三者叠加，不是炫技，而是把部署这件事，从“一次性的手工活”，变成“可重复、可审计、可交接的基础设施代码”。如果你正卡在“网站能跑但不敢动、不敢换服务器、不敢让同事碰”的阶段，这篇内容就是为你写的——它不讲 Ansible 架构原理，不画拓扑图，只给你一套实测通过、删掉注释就能跑、改两行就能复用的完整方案。

2. 整体设计思路与方案选型解析：为什么不用 Docker、不用 GitHub Pages、也不手写 Bash 脚本

拿到“部署静态 HTML 网站”这个需求，技术路径其实很多：GitHub Pages 一键托管、Docker run 一个 nginx:alpine 容器、写个 20 行 Bash 脚本 rsync 同步、甚至用 Python 的 http.server 临时起服务。但每条路背后都有隐性成本，而 Ansible + Ubuntu 20.04 + Nginx 的组合，是在真实运维现场反复权衡后，留下的那个“综合得分最高”的解。

先说为什么不选 GitHub Pages。它确实快，git push就上线。但它锁死了你的控制权：你无法自定义 HTTP 头（比如强制X-Content-Type-Options: nosniff）、无法精细控制缓存策略（Cache-Control: public, max-age=31536000, immutable对字体文件至关重要）、无法配置反向代理做 A/B 测试、更无法在响应前插入一段 Nginx 变量生成的动态时间戳。一旦你需要加一个简单的重定向规则（比如把/old-page.html永久跳转到/new-page.html），Pages 就得求爷爷告奶奶去配_redirects文件，还只支持 Netlify 风格语法。这不是功能缺陷，而是定位差异——Pages 是“发布平台”，而我们要的是“可控的 Web 服务”。

再说Docker 方案的问题。docker run -d -p 80:80 -v $(pwd)/html:/usr/share/nginx/html nginx:alpine一行命令确实能跑。但问题在后续：你怎么管理容器生命周期？docker stop后数据还在，但配置呢？Nginx 的gzip_types、client_max_body_size这些关键参数，是写进容器里还是挂载出来？挂载的话，配置文件放哪？怎么和 HTML 内容一起版本化？更现实的是，Ubuntu 20.04 服务器上，你得先装 Docker Engine，再配 daemon.json，再处理 cgroup v2 兼容性（20.04 默认用 v2，老版 Docker 会报错），这一套下来，已经比 Ansible 的apt install ansible多出三倍操作。Docker 的价值在于隔离和可移植，而静态网站根本不需要隔离——它连 libc 都不调用，直接喂给内核的 sendfile() 系统调用。为零依赖加一层容器，是典型的“杀鸡用牛刀”。

至于手写 Bash 脚本，我见过最“优雅”的版本是 83 行，带颜色输出和进度条。但它本质仍是“一次性脚本”：没有幂等性（重复执行可能创建重复目录、覆盖错误配置）、没有失败回滚（cp -r覆盖了旧文件却忘了备份，就真没了）、没有状态检查（nginx -t检查失败后，脚本是退出还是硬重启？）。更重要的是，它无法描述“期望状态”——Ansible 的核心思想是“声明式”：你告诉它“我要 Nginx 运行着，配置文件是 A，网页文件在 B 目录”，它自己去比对当前状态，缺啥补啥，多啥删啥。Bash 是“过程式”：你写“先 apt update，再 apt install nginx，再 cp 文件，再 systemctl restart”，一旦中间某步失败（比如网络超时），后续步骤全废，你还得手动清理半截状态。

所以最终选定 Ansible，是因为它完美匹配这个场景的三个刚性需求：
第一，幂等性必须强——部署脚本可以每天执行十次，结果完全一致；
第二，可读性必须高——三个月后你回来改配置，看 YAML 比看 Bash 更容易懂“这里到底在干啥”；
第三，无代理、无客户端——Ubuntu 20.04 只需开 SSH，Ansible 控制机（你本机）用 Python 跑起来就行，不用在目标机装任何额外 agent。

我们用 Ubuntu 20.04 而非 22.04 或 24.04，是因 20.04 的 Nginx 1.18.0 在静态文件处理上有一个关键优化：它默认启用sendfile on且tcp_nopush on，这意味着大文件（如视频、PDF）传输时，内核能直接把磁盘页送入 socket 缓冲区，避免用户态内存拷贝，实测比 22.04 的 1.18.0（默认tcp_nopush off）在 100MB 文件下载上快 12%。这不是玄学，是strace -e trace=sendfile,writev抓出来的系统调用差异。而选择 Nginx 而非 Caddy 或 Traefik，是因为它的配置语法极度直白——location / { root /var/www/mysite; }这一行，比 Caddy 的reverse_proxy语义或 Traefik 的 label 标注，更贴近“静态网站”这个单一职责的本质。简单，就是在这里最高的工程美德。

3. 核心细节解析与实操要点：从 Ansible 基础结构到 Nginx 静态服务的每一处关键配置

一个能落地的 Ansible 部署方案，绝不是把apt install nginx和cp -r塞进 playbook 就完事。它必须覆盖从环境初始化、权限控制、安全加固到性能调优的全链路细节。下面拆解这套方案里五个不可妥协的核心环节，每个都附带“为什么这么设”和“不这么设会怎样”的实战推演。

3.1 目录结构设计：为什么/var/www/mysite/不能直接放html/，而要多一层current/

初学者常犯的错误，是把网站文件直接扔进/var/www/mysite/，然后 Nginx 配置root /var/www/mysite;。这看似合理，但埋下两个隐患：一是更新时文件覆盖风险，二是无法实现原子化切换。想象一下，你正在用rsync同步一个 500MB 的图片库，同步到一半时网络断了，此时/var/www/mysite/里一半是旧文件、一半是新文件，Nginx 仍在服务，用户刷到的可能是损坏的 CSS 或缺失的 JS。Ansible 的copy模块虽有校验，但无法规避传输中断。

我们的解法是引入符号链接层：实际文件存放在/var/www/mysite/releases/20240520143000/（时间戳命名），然后创建/var/www/mysite/current指向它，Nginx 的root指向/var/www/mysite/current。每次部署，Ansible 先创建新 release 目录，完整同步文件，再用file模块原子化更新current链接。这样，切换瞬间完成，旧文件毫发无损，随时可回滚。具体实现如下：

- name: Create releases directory file: path: /var/www/mysite/releases state: directory mode: '0755' - name: Create new release directory with timestamp command: "mkdir -p /var/www/mysite/releases/{{ ansible_date_time.iso8601_micro | regex_replace('\\..*', '') | replace(':', '') }}" register: release_dir_result - name: Set release directory path set_fact: release_path: "/var/www/mysite/releases/{{ ansible_date_time.iso8601_micro | regex_replace('\\..*', '') | replace(':', '') }}" - name: Copy website files to new release copy: src: "./html/" dest: "{{ release_path }}/" owner: www-data group: www-data mode: '0644' # 关键：递归设置目录权限，否则子目录可能继承 0755 导致文件不可读 directory_mode: '0755' - name: Update current symlink atomically file: src: "{{ release_path }}" dest: /var/www/mysite/current state: link force: yes

提示：ansible_date_time.iso8601_micro获取精确到微秒的时间戳，regex_replace和replace用于去掉小数点和冒号，生成20240520143000这类纯数字目录名，避免空格或特殊字符引发 shell 解析错误。force: yes确保链接更新是原子操作——先删旧链，再建新链，中间无间隙。

3.2 用户与权限模型：为什么坚持用www-data而非root，以及setfacl的必要性

Nginx 主进程以root运行（需要绑定 80 端口），但工作进程默认以www-data用户身份读取文件。这是 Linux 安全基石：最小权限原则。如果你把 HTML 文件chown root:root，Nginx 工作进程会因无读取权限而返回 403 Forbidden。但若全设为www-data:www-data，又带来另一个风险：如果网站存在 PHP 或 CGI 脚本（哪怕你当前没用），攻击者上传恶意脚本后，它将以www-data权限执行，可能横向渗透同组其他服务。

我们的权限模型分三层：

• 文件所有者：www-data（确保 Nginx 可读）
• 文件所属组：www-data（保持一致性）
• 补充 ACL 权限：给部署用户（如deploy）添加r-x权限，使其能ls和cd，但不能rm或chmod

这通过setfacl实现，而非简单chmod 755：

- name: Set base permissions for web root file: path: /var/www/mysite owner: www-data group: www-data mode: '0755' - name: Set ACL for deploy user to access releases acl: path: /var/www/mysite/releases entity: deploy etype: user permissions: rx state: present - name: Ensure current symlink is readable file: path: /var/www/mysite/current owner: www-data group: www-data mode: '0777' # 符号链接自身权限无关紧要，但需确保指向的目录可读

注意：mode: '0777'设在 symlink 上是安全的，因为 symlink 的权限位在 Linux 中被忽略，真正起作用的是它指向的目标目录权限。这里设0777是为了消除某些老旧 Ansible 版本对 symlink 权限的误判警告。

3.3 Nginx 配置的四大安全基线：从server_tokens到add_header

一个暴露Server: nginx/1.18.0 (Ubuntu)的响应头，等于告诉攻击者你用的是哪个版本的 Nginx，而 CVE-2021-23017（DNS rebinding）正是影响 1.18.0 的一个已知漏洞。因此，Nginx 配置不是“能用就行”，而是必须满足四条安全基线：

1. 隐藏版本号：server_tokens off;—— 防止泄露具体版本，增加攻击者信息收集成本；
2. 禁用危险 HTTP 方法：limit_except GET HEAD POST { deny all; }—— 静态网站根本不需要 PUT、DELETE，一律拒绝；
3. 强制安全响应头：add_header X-Frame-Options "DENY";、add_header X-Content-Type-Options "nosniff";、add_header X-XSS-Protection "1; mode=block";—— 这三条是现代浏览器防御点击劫持、MIME 类型混淆、XSS 的基础盾牌；
4. 限制上传大小：client_max_body_size 1m;—— 即使你没开上传接口，也要防住恶意构造的大体积 POST 请求耗尽内存。

完整 server 块配置如下（保存为templates/nginx-site.conf.j2）：

server { listen 80; server_name {{ domain_name | default('localhost') }}; root /var/www/mysite/current; index index.html; # 安全基线 1：隐藏版本 server_tokens off; # 安全基线 2：仅允许安全方法 limit_except GET HEAD POST { deny all; } # 安全基线 3：强制安全头 add_header X-Frame-Options "DENY" always; add_header X-Content-Type-Options "nosniff" always; add_header X-XSS-Protection "1; mode=block" always; add_header Referrer-Policy "no-referrer-when-downgrade" always; add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;" always; # 安全基线 4：限制请求体 client_max_body_size 1m; # 静态文件性能优化 location ~* \.(?:css|js|jpg|jpeg|gif|png|ico|cur|gz|svg|svgz|mp4|ogg|ogv|webm|htc)$ { expires 1y; add_header Cache-Control "public, immutable, max-age=31536000"; # 启用 gzip 压缩（对文本类资源） gzip on; gzip_vary on; gzip_min_length 1024; gzip_types text/plain text/css text/xml text/javascript application/javascript application/x-javascript application/xml application/xml+rss; } # 防止 .htaccess、.env 等敏感文件被直接访问 location ~ /\. { deny all; } }

注意：add_header ... always中的always参数至关重要。默认情况下，Nginx 只对成功响应（2xx）添加头，而always确保 4xx、5xx 错误页也携带这些安全头，防止错误页成为绕过防护的缺口。

3.4 Ansible Playbook 的幂等性保障：stat模块检查与changed_when的精准控制

Ansible 的“幂等性”不是自动获得的，而是靠每个任务显式声明“什么情况下算 changed”。比如copy模块，当源文件和目标文件的 checksum 一致时，它默认不标记 changed；但command模块执行nginx -t，无论配置是否变化，只要命令成功，它就标记 changed——这会导致后续systemctl reload nginx总是触发，造成不必要的服务抖动。

我们必须用stat模块预先检查 Nginx 配置文件的修改时间，并用changed_when精准控制：

- name: Check if nginx config has changed stat: path: /etc/nginx/sites-available/mysite register: nginx_config_stat - name: Deploy nginx configuration template: src: templates/nginx-site.conf.j2 dest: /etc/nginx/sites-available/mysite owner: root group: root mode: '0644' notify: Reload nginx # 仅当文件内容实际变化时才触发 changed changed_when: nginx_config_stat.stat.exists == false or nginx_config_stat.stat.checksum != (lookup('file', 'templates/nginx-site.conf.j2') | hash('sha1')) - name: Enable site by creating symlink file: src: /etc/nginx/sites-available/mysite dest: /etc/nginx/sites-enabled/mysite state: link force: yes notify: Reload nginx

这里的关键是changed_when表达式：它先判断目标文件是否存在，若不存在（首次部署），必然 changed；若存在，则计算模板文件的 SHA1 校验和，与目标文件当前校验和对比。只有不同时，才认为配置有变更。lookup('file', ...)是 Ansible 内置函数，直接读取控制机上的模板文件内容，hash('sha1')计算其哈希值，整个过程不依赖目标机，稳定可靠。

3.5 日志与监控的轻量化接入：用logrotate和tail -f构建可观测性

生产环境没有日志，就像开车不看仪表盘。但为静态网站上 ELK 或 Prometheus，是过度设计。我们用最轻量的方式接入可观测性：

• Nginx 访问日志：按天轮转，保留 30 天，压缩归档；
• Ansible 部署日志：记录每次执行的 playbook 名、目标主机、开始/结束时间、变更统计；
• 实时调试：tail -f /var/log/nginx/access.log快速验证请求是否到达。

logrotate配置通过 Ansible 的copy模块部署：

- name: Deploy logrotate config for nginx copy: content: | /var/log/nginx/*.log { daily missingok rotate 30 compress delaycompress notifempty create 0644 www-data www-data sharedscripts postrotate if [ -f /var/run/nginx.pid ]; then kill -USR1 `cat /var/run/nginx.pid` fi endscript } dest: /etc/logrotate.d/nginx-mysite owner: root group: root mode: '0644'

提示：postrotate中的kill -USR1是 Nginx 的“重新打开日志文件”信号，比systemctl reload nginx更轻量，不中断连接。delaycompress确保刚轮转的日志先不压缩，方便快速zcat查看。

4. 实操过程与核心环节实现：从零开始搭建 Ubuntu 20.04 服务器到首次成功访问

现在，我们把前面所有设计，组装成一套可立即执行的完整流程。假设你有一台全新的 Ubuntu 20.04 云服务器（IP：192.168.1.100），SSH 密钥已配置好，用户名为ubuntu。整个过程分为四个阶段：Ansible 控制机准备、目标服务器初始化、Playbook 编写与执行、首次访问验证。每一步都附带命令、预期输出和常见卡点。

4.1 控制机环境准备：Python、Ansible 与项目目录结构

Ansible 控制机可以是你的 macOS 笔记本、Windows WSL2，或另一台 Linux 机器。核心要求是：Python 3.6+、pip、ssh 客户端。以 macOS 为例：

# 1. 确保 Python 3.9+（macOS 自带 Python 3.9） python3 --version # 应输出 3.9.x 或更高 # 2. 升级 pip 并安装 ansible（推荐用 pip，避免 brew 版本滞后） pip3 install --upgrade pip pip3 install ansible==7.6.0 # 固定版本，避免新版本 breaking change # 3. 创建项目目录 mkdir -p my-static-site/{files,templates,roles} cd my-static-site # 4. 初始化 Ansible 配置 cat > ansible.cfg << 'EOF' [defaults] inventory = ./inventory remote_user = ubuntu private_key_file = ~/.ssh/id_rsa host_key_checking = False deprecation_warnings = False stdout_callback = yaml EOF # 5. 创建 inventory 文件（定义目标主机） cat > inventory << 'EOF' [webservers] 192.168.1.100 EOF

注意：host_key_checking = False仅用于首次连接免交互确认，生产环境应改为True并预置 known_hosts。stdout_callback = yaml让输出更易读，显示为结构化 YAML 而非 JSON。

4.2 目标服务器初始化：Ubuntu 20.04 的最小化加固

新装的 Ubuntu 20.04 默认开启ufw防火墙，但只放行 SSH（22 端口），我们需要开放 HTTP（80）和 HTTPS（443）。同时，创建专用部署用户deploy，禁用密码登录，仅用 SSH 密钥：

# 在目标服务器上执行（或用 Ansible ad-hoc 命令） # 1. 更新系统并安装基础工具 sudo apt update && sudo apt upgrade -y sudo apt install -y python3-pip python3-venv # 2. 开放防火墙端口 sudo ufw allow OpenSSH sudo ufw allow 'Nginx Full' # 自动放行 80 和 443 sudo ufw --force enable # 3. 创建 deploy 用户并配置密钥登录 sudo adduser --disabled-password --gecos "" deploy sudo usermod -aG sudo deploy # 将你的公钥（~/.ssh/id_rsa.pub）内容追加到 /home/deploy/.ssh/authorized_keys # 并设置正确权限 sudo mkdir -p /home/deploy/.ssh sudo chown -R deploy:deploy /home/deploy/.ssh sudo chmod 700 /home/deploy/.ssh sudo chmod 600 /home/deploy/.ssh/authorized_keys

实操心得：adduser --disabled-password创建无密码用户，比useradd更安全，它会自动创建家目录和 shell。ufw allow 'Nginx Full'是 Ubuntu 的预设应用配置，比手动ufw allow 80更可靠，因为它还包含 IPv6 规则。

4.3 编写主 Playbook：deploy.yml的完整内容与变量注入

现在，编写核心 Playbookdeploy.yml。它将调用多个角色（roles），但为简化，我们先写成单文件。内容涵盖：安装 Nginx、部署网站文件、配置 Nginx、启动服务、验证访问。

--- - name: Deploy Static HTML Website to Ubuntu 20.04 hosts: webservers become: yes vars: domain_name: "mysite.local" # 可在命令行用 -e "domain_name=example.com" 覆盖 site_root: "/var/www/mysite" nginx_config_name: "mysite" tasks: # 1. 安装 Nginx - name: Install nginx package apt: name: nginx state: present update_cache: yes # 2. 创建网站根目录结构 - name: Create site root directories file: path: "{{ item }}" state: directory mode: '0755' owner: www-data group: www-data loop: - "{{ site_root }}" - "{{ site_root }}/releases" - "{{ site_root }}/shared" # 3. 部署 HTML 文件（假设本地 html/ 目录存在） - name: Deploy website files copy: src: "./html/" dest: "{{ site_root }}/releases/{{ ansible_date_time.iso8601_micro | regex_replace('\\..*', '') | replace(':', '') }}/" owner: www-data group: www-data mode: '0644' directory_mode: '0755' register: deploy_files # 4. 设置 current symlink - name: Set current release symlink file: src: "{{ site_root }}/releases/{{ ansible_date_time.iso8601_micro | regex_replace('\\..*', '') | replace(':', '') }}" dest: "{{ site_root }}/current" state: link force: yes # 5. 部署 Nginx 配置 - name: Deploy nginx site configuration template: src: templates/nginx-site.conf.j2 dest: "/etc/nginx/sites-available/{{ nginx_config_name }}" owner: root group: root mode: '0644' notify: Reload nginx # 6. Enable the site - name: Enable nginx site file: src: "/etc/nginx/sites-available/{{ nginx_config_name }}" dest: "/etc/nginx/sites-enabled/{{ nginx_config_name }}" state: link force: yes notify: Reload nginx # 7. Disable default site to avoid conflict - name: Disable default nginx site file: path: /etc/nginx/sites-enabled/default state: absent notify: Reload nginx # 8. Start and enable nginx service - name: Ensure nginx is started and enabled service: name: nginx state: started enabled: yes handlers: - name: Reload nginx service: name: nginx state: reloaded

关键技巧：notify: Reload nginx是 Ansible 的 handler 机制，它确保只有当上述任一任务标记为 changed 时，才会触发Reload nginx。这比在每个任务后加service: nginx state=reloaded更高效，避免重复 reload。

4.4 执行部署与首次验证：从ansible-playbook到浏览器访问

一切就绪，执行部署：

# 1. 首先，确保本地有 html/ 目录（可从网上找一个简单的 HTML 页面） mkdir -p html cat > html/index.html << 'EOF' <!doctype html> <html lang="zh-cn"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>My Static Site</title> <style>body{font-family:sans-serif;text-align:center;margin-top:10%;color:#333;}</style> </head> <body> <h1>✅ Deployment Successful!</h1> <p>This page was deployed via Ansible on Ubuntu 20.04 with Nginx.</p> <p>Server time: <span id="time"></span></p> <script>document.getElementById('time').textContent = new Date().toString();</script> </body> </html> EOF # 2. 执行 playbook（加 -v 查看详细输出） ansible-playbook deploy.yml -v # 3. 验证 Nginx 是否运行 ansible webservers -m command -a "systemctl is-active nginx" -v # 4. 验证端口监听 ansible webservers -m command -a "ss -tlnp | grep :80" -v

预期输出中，ansible-playbook应显示ok=8 changed=5 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0，其中changed=5表示安装了 Nginx、创建了目录、复制了文件、设置了链接、部署了配置。systemctl is-active nginx应返回active，ss -tlnp应显示nginx进程监听*:80。

最后，在浏览器访问http://192.168.1.100，你应该看到那个绿色的 ✅ 页面。打开开发者工具 Network 面板，检查响应头，确认Server字段为空（server_tokens off生效），X-Frame-Options等安全头存在，Cache-Control对 HTML 是max-age=0（因未设 expires），对 CSS/JS 是max-age=31536000（因 location 块匹配了扩展名）。

常见问题排查：如果页面 403，立刻执行ansible webservers -m command -a "ls -l /var/www/mysite/current/"，检查文件所有者是否为www-data；如果 404，执行ansible webservers -m command -a "nginx -t"，看配置语法是否错误；如果连接被拒绝，执行ansible webservers -m command -a "ufw status verbose"，确认 80 端口已放行。

5. 常见问题与排查技巧实录：那些 Ansible 报错信息背后的真实原因

在真实部署中，Ansible 的报错信息往往像谜语。下面整理六类高频问题，每类都给出原始报错、根本原因、三步排查法和永久解决方案。这些不是文档里的标准答案，而是我在凌晨三点对着 terminal 反复strace和journalctl后，记在咖啡杯底的笔记。

5.1 “Failed to connect to the host via ssh”：SSH 连接被拒的七种可能

原始报错：

FAILED! => {"msg": "Failed to connect to the host via ssh: ssh: connect to host 192.168.1.100 port 22: Connection refused"}

根本原因：不是密码错，而是 SSH 服务根本没在监听 22 端口。Ubuntu 20.04 默认安装openssh-server，但某些云厂商镜像会禁用它，或防火墙彻底屏蔽。

三步排查：

1. ping 192.168.1.100确认网络层可达；
2. nc -zv 192.168.1.100 22测试端口是否开放（nc是 netcat）；
3. 若不通，在目标机执行sudo systemctl status ssh，看状态是否为active (running)。

永久方案：

• 在目标机执行sudo systemctl enable --now ssh确保开机自启；
• 检查/etc/ssh/sshd_config中Port 22和ListenAddress是否被注释或改错；
• sudo ufw allow OpenSSH放行防火墙。

注意：Connection refused和Connection timed out有本质区别。前者是端口明确拒绝（服务未运行），后者是网络层无响应（防火墙拦截或路由问题）。

5.2 “Permission denied (publickey)”：密钥认证失败的权限陷阱

原始报错：

FAILED! => {"msg": "Failed to connect to the host via ssh: ubuntu@192.168.1.100: Permission denied (publickey)."}

根本原因：Ansible 用你的私钥~/.ssh/id_rsa去连，但目标机/home/ubuntu/.ssh/authorized_keys里没有对应的公钥，或权限设置错误（SSH 协议强制要求.ssh目录权限 ≤ 0700，authorized_keys≤ 0600）。

三步排查：

1. ssh -i ~/.ssh/id_rsa ubuntu@192.168.1.100手动测试，确认是同一错误；
2. 在目标机执行ls -ld ~/.ssh ~/.ssh/authorized_keys，检查权限；
3. cat ~/.ssh/authorized_keys确认你的公钥是否在其中（ssh-keygen -l -f ~/.ssh/id_rsa.pub查看指纹，再比对）。

永久方案：

• chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys；
• 用ssh-copy-id -i ~/.ssh/id_rsa.pub ubuntu@192.168.1.100自动追加公钥；
• 在ansible.cfg中显式指定private_key_file = ~/.ssh/id_rsa，避免 Ansible 乱猜。

5.3 “The conditional check '