diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..ec0a8ae --- /dev/null +++ b/.gitattributes @@ -0,0 +1,9 @@ +* text=auto +.gitattributes text eol=lf +*.md text eol=lf +*.yml text eol=lf +*.yaml text eol=lf +*.json text eol=lf +*.sh text eol=lf +*.ps1 text eol=lf +*.txt text eol=lf diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..c11e04e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,24 @@ +name: 错误反馈 +description: 反馈手册中的错误命令、错误说明或过时内容 +title: "[错误反馈] " +labels: ["bug", "documentation"] +body: + - type: textarea + id: location + attributes: + label: 问题位置 + description: 请粘贴章节标题、链接或相关命令。 + validations: + required: true + - type: textarea + id: problem + attributes: + label: 具体问题 + description: 请描述哪里不正确，以及你的系统环境。 + validations: + required: true + - type: textarea + id: expected + attributes: + label: 建议修正 + description: 如果你知道正确写法，可以直接贴出来。 diff --git a/.github/ISSUE_TEMPLATE/command-request.yml b/.github/ISSUE_TEMPLATE/command-request.yml new file mode 100644 index 0000000..7a9e45e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/command-request.yml @@ -0,0 +1,30 @@ +name: 命令补充 +description: 建议补充一个命令或场景 +title: "[命令补充] " +labels: ["documentation", "command-request"] +body: + - type: dropdown + id: platform + attributes: + label: 适用平台 + options: + - Windows PowerShell + - Linux + - 银河麒麟 + - 统信 UOS + - 跨平台 + validations: + required: true + - type: textarea + id: command + attributes: + label: 命令或场景 + description: 请写出命令、使用场景和期望补充的位置。 + placeholder: 例如: 查看 8080 端口占用并结束进程 + validations: + required: true + - type: textarea + id: notes + attributes: + label: 补充说明 + description: 如果命令有风险、版本限制或依赖工具，请一并说明。 diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..af6b09c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: 阅读贡献指南 + url: https://github.com/shiwenxin123/PowerShell-Linux-/blob/main/CONTRIBUTING.md + about: 提交 Issue 或 PR 前建议先阅读贡献指南。 diff --git a/.github/ISSUE_TEMPLATE/troubleshooting-case.yml b/.github/ISSUE_TEMPLATE/troubleshooting-case.yml new file mode 100644 index 0000000..acb8a57 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/troubleshooting-case.yml @@ -0,0 +1,29 @@ +name: 故障案例补充 +description: 建议补充一个真实运维故障案例 +title: "[故障案例] " +labels: ["documentation", "troubleshooting"] +body: + - type: textarea + id: symptom + attributes: + label: 故障现象 + description: 请描述用户看到的现象、报错或告警。 + placeholder: 例如: Grafana 面板显示 No data，Prometheus target 为 down + validations: + required: true + - type: textarea + id: environment + attributes: + label: 环境信息 + description: 请说明系统、组件、版本或部署方式。 + placeholder: 例如: Kubernetes 1.28、Prometheus Operator、Nginx 1.24 + - type: textarea + id: checks + attributes: + label: 已尝试排查 + description: 请列出已经执行过的命令、日志或排查结论。 + - type: textarea + id: expected + attributes: + label: 期望补充内容 + description: 请说明希望文档补充哪些命令、处理建议或风险提醒。 diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 0000000..8fcaee9 --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,33 @@ +- name: documentation + color: "0075ca" + description: 文档新增或修改 +- name: command-request + color: "0e8a16" + description: 新命令或新场景建议 +- name: bug + color: "d73a4a" + description: 错误命令、错误说明或过时内容 +- name: good first issue + color: "7057ff" + description: 适合第一次贡献 +- name: help wanted + color: "008672" + description: 欢迎社区协助 +- name: security + color: "b60205" + description: 高危命令或安全风险 +- name: powershell + color: "012456" + description: PowerShell 相关内容 +- name: linux + color: "f0db4f" + description: Linux 相关内容 +- name: kylin + color: "c5def5" + description: 银河麒麟相关内容 +- name: uos + color: "bfdadc" + description: 统信 UOS 相关内容 +- name: containers + color: "1d76db" + description: Docker 或 Kubernetes 相关内容 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..a58dd28 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,18 @@ +## 变更内容 + +- + +## 变更类型 + +- [ ] 修正文档错误 +- [ ] 补充命令 +- [ ] 新增专题 +- [ ] 改进示例脚本 +- [ ] 其他 + +## 检查清单 + +- [ ] 命令已在对应环境验证，或已注明版本限制 +- [ ] 高危命令已标注风险 +- [ ] 未包含真实密码、Token、内网地址等敏感信息 +- [ ] Markdown 表格和代码块可以正常渲染 diff --git a/.github/workflows/docs-site.yml b/.github/workflows/docs-site.yml new file mode 100644 index 0000000..e233aec --- /dev/null +++ b/.github/workflows/docs-site.yml @@ -0,0 +1,54 @@ +name: Docs Site + +on: + push: + branches: + - main + - master + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: "3.x" + + - name: Install MkDocs + run: pip install -r requirements.txt + + - name: Build site + run: mkdocs build --strict + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: site + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: build + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/markdown-check.yml b/.github/workflows/markdown-check.yml new file mode 100644 index 0000000..6159297 --- /dev/null +++ b/.github/workflows/markdown-check.yml @@ -0,0 +1,30 @@ +name: Markdown Check + +on: + pull_request: + push: + branches: + - main + - master + +jobs: + markdown-check: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run documentation checks + shell: pwsh + run: ./scripts/check-docs.ps1 + + markdownlint: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run markdownlint + uses: DavidAnson/markdownlint-cli2-action@v17 + with: + globs: "**/*.md" diff --git a/.github/workflows/script-quality.yml b/.github/workflows/script-quality.yml new file mode 100644 index 0000000..1496784 --- /dev/null +++ b/.github/workflows/script-quality.yml @@ -0,0 +1,104 @@ +name: Script Quality + +on: + pull_request: + push: + branches: + - main + - master + +jobs: + shellcheck: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run ShellCheck + uses: ludeeus/action-shellcheck@master + with: + scandir: ./scripts + + psscriptanalyzer: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install PSScriptAnalyzer + shell: pwsh + run: Install-Module PSScriptAnalyzer -Force -Scope CurrentUser + + - name: Run PSScriptAnalyzer + shell: pwsh + run: Invoke-ScriptAnalyzer -Path ./scripts -Recurse -Severity Warning,Error + + linux-health-check: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Validate JSON schema file + run: python -m json.tool docs/schema/health-check-report.schema.json > /dev/null + + - name: Check Bash syntax + run: bash -n scripts/linux-health-check.sh + + - name: Validate JSON output + run: | + bash scripts/linux-health-check.sh --module system --format json > linux-health-check.json + python -m json.tool linux-health-check.json > /dev/null + + - name: Validate output file + run: | + bash scripts/linux-health-check.sh --module disk --format json --output reports/linux-health-check.json > /dev/null + test -s reports/linux-health-check.json + python -m json.tool reports/linux-health-check.json > /dev/null + + - name: Validate parameter exit code + run: | + set +e + bash scripts/linux-health-check.sh --format invalid + code=$? + set -e + test "$code" -eq 2 + + windows-health-check: + runs-on: windows-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Check PowerShell syntax + shell: pwsh + run: | + $parseErrors = $null + [System.Management.Automation.PSParser]::Tokenize((Get-Content -Raw 'scripts/windows-health-check.ps1'), [ref]$parseErrors) | Out-Null + if ($parseErrors) { + $parseErrors | Format-List | Out-String | Write-Error + exit 1 + } + + - name: Validate JSON output + shell: pwsh + run: | + $json = ./scripts/windows-health-check.ps1 -Module process -Format json | ConvertFrom-Json + if ($json.metadata.format -ne 'json') { throw 'Unexpected metadata.format' } + if (-not $json.modules.process) { throw 'Missing process module' } + + - name: Validate output file + shell: pwsh + run: | + ./scripts/windows-health-check.ps1 -Module process -Format json -OutputFile reports/windows-health-check.json | Out-Null + $json = Get-Content -Raw reports/windows-health-check.json | ConvertFrom-Json + if ($json.metadata.script -ne 'windows-health-check.ps1') { throw 'Unexpected script metadata' } + + - name: Validate parameter exit code + shell: pwsh + run: | + pwsh -NoProfile -ExecutionPolicy Bypass -File ./scripts/windows-health-check.ps1 -Format invalid + if ($LASTEXITCODE -ne 2) { + throw "Expected exit code 2, got $LASTEXITCODE" + } + exit 0 diff --git a/.github/workflows/secret-scan.yml b/.github/workflows/secret-scan.yml new file mode 100644 index 0000000..f658946 --- /dev/null +++ b/.github/workflows/secret-scan.yml @@ -0,0 +1,22 @@ +name: Secret Scan + +on: + pull_request: + push: + branches: + - main + - master + +jobs: + gitleaks: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Run Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..98cca63 --- /dev/null +++ b/.gitignore @@ -0,0 +1,19 @@ +# OS / editor +.DS_Store +Thumbs.db +.idea/ +.vscode/ + +# Temporary files +*.tmp +*.bak +*.swp + +# Logs +*.log + +# Generated reports +reports/ + +# MkDocs build output +site/ diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000..3faad37 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,6 @@ +default: true +MD013: false +MD033: false +MD041: false +MD024: + siblings_only: true diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d398d05 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,153 @@ +# Changelog + +## 2.16.0 + +- README 和文档站首页新增学习路线，覆盖新手、运维值班、国产 Linux、容器/Kubernetes 和脚本自动化。 +- 案例库新增按症状查找索引。 +- 新增 v2.16.0 Release 草案，补充 GitHub About、发布文案和推荐阅读。 +- 更新维护者指南，补充后续 good first issue 候选方向。 +- 新增 Good First Issues 清单和故障案例补充 Issue 模板。 +- 新增 Kubernetes DNS 异常、Prometheus Target Down、Grafana 无数据排查案例。 +- 主手册收口第 1 批: 补充 Kylin/UOS 厂商命令细节、企业级日志配置样例和跨平台工具分类。 +- 新增 Linux 性能调优专题，覆盖 sysctl、limits、磁盘 I/O、网络连接和变更建议。 +- Linux 巡检脚本新增 JSON 输出，使用统一 metadata/modules/summary/errors 结构。 +- Windows 巡检脚本新增 JSON 输出，使用 PowerShell 对象和 `ConvertTo-Json` 生成结构化报告。 +- 巡检脚本新增明确退出码: 0 正常、1 告警、2 参数错误、3 内部异常或输出失败。 +- 新增 Linux 和 Windows JSON 示例报告。 +- 新增巡检脚本工具化文档。 +- 新增 Health Check Report JSON Schema，明确自动化消费字段契约。 +- 新增巡检脚本 GitHub Actions 功能测试，覆盖 JSON 输出、输出文件和参数错误退出码。 +- README 顶部新增 Docs、Markdown、Script Quality、Secret Scan 和 License badges。 +- `requirements.txt` 增加 MkDocs、Material for MkDocs 和 pymdown-extensions 版本范围。 +- 更新维护者指南和 Release 检查清单，补充依赖维护和本地验证步骤。 +- 新增 FAQ 页面，并挂载到 README、文档站首页和 MkDocs 导航。 +- 更新 README、文档站首页、专题入口、覆盖矩阵和审查报告。 + +## 2.15.0 + +- 新增下一阶段优化计划。 +- 更新项目审查报告，修正已完成事项和剩余重点。 +- 更新 Roadmap，移除已完成的旧目标。 +- 更新 README、文档站首页和 MkDocs 导航。 + +## 2.14.0 + +- 迁移 PowerShell 高级技巧章节，覆盖管道、对象、变量、控制流、函数和错误处理。 +- 迁移 Linux 用户、组与权限章节。 +- 迁移 Shell 脚本基础与高级技巧章节。 +- 迁移 Python 与 Node.js 跨平台脚本章节。 +- 迁移 Keepalived 高可用章节。 +- 更新主手册专题化迁移进度、文档站导航、首页和专题化手册入口。 + +## 2.13.0 + +- 迁移主手册 Linux 网络章节到专题页，补充 mtr、dig、scp、sftp、rsync、SSH 转发等命令。 +- 新增 Linux 系统监控与日志专题。 +- 新增 Docker 与 Kubernetes 生产级命令专题。 +- 新增主手册专题化迁移进度表。 +- 更新 README、文档站首页、MkDocs 导航和专题化手册入口。 + +## 2.12.0 + +- 新增 Git、SSH、curl 与 jq 开发排障工具专题。 +- 新增 PromQL、LogQL 与告警规则专题。 +- 扩展命令索引，补充 Git、SSH、curl、jq、PromQL、LogQL。 +- 更新文档站导航、首页、专题化手册入口和命令覆盖矩阵。 + +## 2.11.0 + +- 新增 PostgreSQL、MongoDB 与 Elasticsearch 专题。 +- 新增云服务器与负载均衡排查专题，覆盖安全组、NAT、云盘、负载均衡健康检查。 +- 新增集中日志与监控告警专题，覆盖 Prometheus、Node Exporter、Alertmanager、Grafana、Loki、ELK。 +- 更新文档站导航、首页、专题化手册入口和命令覆盖矩阵。 + +## 2.10.0 + +- 新增数据库与中间件命令专题，覆盖 MySQL、Redis、Nginx、RabbitMQ、Kafka。 +- 新增日志轮转、审计与系统日志专题，覆盖 journalctl、logrotate、rsyslog、auditd。 +- 新增 sudoers 与 AppArmor 专题。 +- 新增国产 Linux 版本差异与排查要点。 +- 更新文档站导航、首页、专题化手册入口和命令覆盖矩阵。 + +## 2.9.0 + +- 新增 Linux 包管理专题，覆盖 apt、dpkg、yum、dnf、rpm 和软件源排查。 +- 新增 Linux 磁盘、挂载与 LVM 专题。 +- 新增防火墙与 SELinux 专题，覆盖 firewalld、ufw、iptables、nftables、SELinux。 +- 新增 Windows 管理命令专题，覆盖事件日志、注册表、计划任务、防火墙、远程管理。 +- 新增 Kubernetes 进阶排查专题，覆盖 Service、Endpoints、Ingress、PVC/PV、Node、Helm。 +- 更新文档站导航、首页、专题化手册入口和命令覆盖矩阵。 + +## 2.8.0 + +- 新增命令覆盖矩阵，用于评估 PowerShell、Linux、Windows、容器、国产 Linux、数据库和中间件等领域覆盖程度。 +- 扩展命令索引，补充包管理、网络诊断、日志、安全、磁盘挂载、LVM、Windows 管理、Kubernetes、数据库与中间件命令族。 +- 更新 README、文档站首页和 MkDocs 导航。 + +## 2.7.0 + +- Linux 和 Windows 巡检脚本支持模块化检查。 +- Linux 和 Windows 巡检脚本支持 Markdown 报告输出。 +- 新增 Kubernetes ImagePullBackOff、Docker Compose 启动失败、TLS 证书链不完整故障案例。 +- 新增 Secret Scan 工作流。 +- 文档检查脚本增加基础敏感信息模式扫描。 +- 更新 README、MkDocs 导航和项目审查报告。 + +## 2.6.0 + +- 精简 README 第一屏快速入口，将完整导航交给文档站首页。 +- 新增 markdownlint 配置。 +- 新增 Script Quality 工作流，加入 ShellCheck 和 PSScriptAnalyzer。 +- 新增 Nginx 502/504、MySQL 启动失败、Redis 连接失败、Java OOM 故障案例。 +- 更新项目审查报告和 MkDocs 导航。 + +## 2.5.0 + +- 新增项目整体审查报告，梳理当前不足和后续优先级。 +- 新增 `scripts/check-docs.ps1` 文档检查脚本。 +- 更新 Markdown Check 工作流，改为执行实际文档检查。 +- 修复 README Issue 链接和 Release 检查清单中的相对链接。 + +## 2.4.0 + +- 新增完整手册专题化入口第一阶段。 +- 新增 PowerShell 基础、PowerShell 系统管理专题页。 +- 新增 Linux 基础、网络排查、存储与日志专题页。 +- 新增系统安全加固和跨平台工具专题页。 +- 新增 Nginx 启动失败、DNS 解析失败、证书过期故障案例。 +- 更新 README、文档站首页和 MkDocs 导航。 + +## 2.3.0 + +- 新增真实故障案例库，覆盖磁盘满、CPU 飙高、端口占用、SSH 失败、Docker 重启、Kubernetes CrashLoopBackOff。 +- 扩展命令风险等级说明，按删除、权限、磁盘、网络、防火墙、服务等场景给出执行前检查。 +- 新增国产 Linux 离线安装与软件源维护专题。 +- 新增信创环境架构与兼容性检查专题。 +- Linux 和 Windows 巡检脚本支持保存报告文件。 +- 更新 README、文档站首页和 MkDocs 导航。 + +## 2.2.0 + +- 新增命令索引，便于按关键词快速定位命令。 +- 新增命令风险等级说明和高危命令清单。 +- 新增常见报错排查专题。 +- 新增 Docker 与 Kubernetes 运维速查。 +- 新增 PowerShell 实用场景专题。 +- 新增 Bash 文本处理专题。 +- 新增维护者指南、Release 检查清单和标签配置建议。 +- 更新 README、文档站首页和 MkDocs 导航。 + +## 2.1.0 + +- 新增 README 项目首页，强化项目定位、快速入口和贡献说明。 +- 新增 PowerShell 与 Linux 命令速查表。 +- 新增 GitHub 热度优化清单。 +- 新增 PowerShell 与 Bash 命令对照专题。 +- 新增 Linux 故障应急排查清单。 +- 新增银河麒麟与统信 UOS 常用命令专题。 +- 新增 Linux 和 Windows 巡检示例脚本。 +- 新增贡献指南、License、Issue 模板和 PR 模板。 + +## 2.0.0 + +- 完整手册覆盖 Windows PowerShell、Linux、银河麒麟、统信 UOS、专业运维与安全加固、跨平台脚本与工具。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..dc4c848 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# 贡献指南 + +感谢你愿意完善这个命令手册。这个项目的目标是: 让中文用户能快速、准确、安全地查到 PowerShell、Linux、银河麒麟和统信 UOS 的常用命令。 + +## 可以贡献什么 + +- 补充缺失命令 +- 修正错误命令或过时参数 +- 增加真实运维场景示例 +- 增加 PowerShell 与 Linux 对照 +- 标注高危命令和替代方案 +- 改进排版、目录和可读性 + +## 命令条目建议格式 + +````markdown +### 场景名称 + +```bash +# 简短说明 +command --option value +``` + +说明: +- 适用系统: Linux / PowerShell / 银河麒麟 / 统信 UOS +- 风险等级: 低 / 中 / 高 +- 常见错误: 可选 +```` + +## 提交前检查 + +- 命令可以在对应系统上执行，或者注明版本限制。 +- 高危命令必须写清楚风险。 +- 不提交真实服务器 IP、账号、密码、Token、内网域名等敏感信息。 +- Markdown 表格和代码块可以正常渲染。 +- 中文标点和英文命令之间尽量留一个空格。 + +## Issue 建议 + +提交问题时请尽量包含: + +- 操作系统和版本 +- 命令原文 +- 报错信息 +- 你期望的结果 +- 你认为应该如何修改 + +## Pull Request 建议 + +PR 标题建议使用: + +- `docs: add Linux log commands` +- `fix: correct PowerShell service example` +- `docs: add UOS package management notes` + +小而清晰的 PR 更容易被 review 和合并。 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..38e824b --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 shiwenxin123 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..db43fb5 --- /dev/null +++ b/README.md @@ -0,0 +1,129 @@ +# Windows PowerShell 与 Linux 常用命令手册 + +[![Docs Site](https://github.com/shiwenxin123/PowerShell-Linux-/actions/workflows/docs-site.yml/badge.svg)](https://github.com/shiwenxin123/PowerShell-Linux-/actions/workflows/docs-site.yml) +[![Markdown Check](https://github.com/shiwenxin123/PowerShell-Linux-/actions/workflows/markdown-check.yml/badge.svg)](https://github.com/shiwenxin123/PowerShell-Linux-/actions/workflows/markdown-check.yml) +[![Script Quality](https://github.com/shiwenxin123/PowerShell-Linux-/actions/workflows/script-quality.yml/badge.svg)](https://github.com/shiwenxin123/PowerShell-Linux-/actions/workflows/script-quality.yml) +[![Secret Scan](https://github.com/shiwenxin123/PowerShell-Linux-/actions/workflows/secret-scan.yml/badge.svg)](https://github.com/shiwenxin123/PowerShell-Linux-/actions/workflows/secret-scan.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) + +一份面向桌面用户、运维工程师、国产 Linux 使用者和跨平台脚本学习者的命令速查手册。项目覆盖 Windows PowerShell、Linux、银河麒麟、统信 UOS、安全加固和常见自动化场景，适合日常查阅、教学和内部培训。 + +> 当前主手册: [Windows-PowerShell-Linux-Command-Manual.md](Windows-PowerShell-Linux-Command-Manual.md) + +## 项目亮点 + +- **跨平台对照**: 同时整理 PowerShell 与 Linux 常用命令，便于 Windows/Linux 用户互相迁移。 +- **国产系统适配**: 包含银河麒麟、统信 UOS 相关命令和运维场景。 +- **运维实用导向**: 覆盖文件、进程、服务、网络、日志、安全、脚本自动化等高频工作。 +- **中文友好**: 命令说明以中文为主，降低新手和团队培训成本。 + +## 快速入口 + +| 需求 | 推荐阅读 | +| --- | --- | +| 常见问题 | [FAQ](docs/FAQ.md) | +| 按命令查找 | [命令索引](docs/COMMAND-INDEX.md) | +| 覆盖面评估 | [命令覆盖矩阵](docs/COMMAND-COVERAGE-MATRIX.md) | +| 快速查命令 | [命令速查表](docs/COMMAND-CHEATSHEET.md) | +| 专题化手册 | [完整手册专题化入口](docs/manual/README.md) | +| 迁移进度 | [主手册迁移进度](docs/MANUAL-MIGRATION.md) | +| 下一阶段 | [下一阶段优化计划](docs/NEXT-STAGE-PLAN.md) | +| Linux 应急排障 | [Linux 故障应急排查清单](docs/troubleshooting/LINUX-INCIDENT-CHECKLIST.md) | +| 真实故障案例 | [真实故障案例库](docs/cases/README.md) | +| 国产 Linux 运维 | [银河麒麟与统信 UOS 常用命令](docs/domestic-linux/KYLIN-UOS-COMMANDS.md) | +| 命令安全 | [命令风险等级说明](docs/security/RISK-LEVELS.md) | +| 项目导航 | [文档站首页](docs/index.md) | + +更多专题包括 PowerShell/Bash 对照、Bash 文本处理、Docker/Kubernetes、离线安装、巡检脚本和项目维护内容，请从 [文档站首页](docs/index.md) 进入。 + +## 学习路线 + +| 路线 | 建议顺序 | +| --- | --- | +| 新手入门 | [命令速查表](docs/COMMAND-CHEATSHEET.md) -> [PowerShell 基础](docs/manual/powershell/BASIC.md) -> [Linux 基础](docs/manual/linux/BASIC.md) | +| 运维值班 | [Linux 应急排查](docs/troubleshooting/LINUX-INCIDENT-CHECKLIST.md) -> [真实故障案例](docs/cases/README.md) -> [命令风险等级](docs/security/RISK-LEVELS.md) | +| 国产 Linux | [麒麟与 UOS](docs/domestic-linux/KYLIN-UOS-COMMANDS.md) -> [离线安装](docs/domestic-linux/OFFLINE-PACKAGE-GUIDE.md) -> [版本差异](docs/domestic-linux/VERSION-DIFFERENCES.md) | +| 容器/Kubernetes | [Docker/Kubernetes 生产命令](docs/manual/kubernetes/DOCKER-K8S-PRODUCTION.md) -> [Kubernetes 进阶排查](docs/manual/kubernetes/ADVANCED-TROUBLESHOOTING.md) -> [K8s 故障案例](docs/cases/README.md) | +| 脚本自动化 | [Shell 脚本](docs/manual/linux/SHELL-SCRIPTING.md) -> [跨平台脚本](docs/manual/cross-platform/PYTHON-NODE-SCRIPTS.md) -> [巡检脚本工具化](docs/manual/automation/HEALTH-CHECK-SCRIPTS.md) | + +## 适合谁 + +- 刚开始学习 PowerShell 或 Linux 的用户 +- 经常在 Windows 和 Linux 之间切换的开发者 +- 维护银河麒麟、统信 UOS 等国产系统的运维人员 +- 需要整理内部培训资料、应急命令清单或值班手册的团队 + +## 推荐使用方式 + +1. 先收藏项目，日常遇到命令时直接搜索关键字。 +2. 从 [命令速查表](docs/COMMAND-CHEATSHEET.md) 找到常用命令。 +3. 在完整手册里查看更详细示例。 +4. 发现遗漏或错误时，通过 Issue 或 Pull Request 补充。 + +## 内容规划 + +- [x] PowerShell 常用命令 +- [x] Linux 常用命令 +- [x] 银河麒麟命令场景 +- [x] 统信 UOS 命令场景 +- [x] 运维与安全加固 +- [x] 跨平台脚本与工具 +- [x] PowerShell 与 Bash 对照表 +- [x] Linux 故障应急排查 +- [x] 国产 Linux 专题入口 +- [x] 示例脚本目录 +- [x] GitHub Pages 文档站配置 +- [x] 命令索引 +- [x] 命令风险等级说明 +- [x] 常见报错排查扩展 +- [x] Docker 与 Kubernetes 速查 +- [x] Bash 文本处理专题 +- [x] PowerShell 实用场景专题 +- [x] 维护者指南与 Release 检查清单 +- [x] 真实故障案例库 +- [x] 国产 Linux 离线安装与架构兼容性专题 +- [x] 巡检脚本支持保存报告 +- [x] 巡检脚本支持模块化检查和 Markdown 报告 +- [x] 完整手册专题化入口第一阶段 +- [x] Nginx、DNS、证书过期故障案例 +- [x] ImagePullBackOff、Docker Compose、TLS 证书链案例 +- [x] ShellCheck、PSScriptAnalyzer、markdownlint、敏感信息扫描 +- [x] 命令覆盖矩阵 +- [x] 数据库与中间件命令专题 +- [x] 日志轮转、auditd、rsyslog 专题 +- [x] sudoers 与 AppArmor 专题 +- [x] 国产 Linux 版本差异专题 +- [x] PostgreSQL、MongoDB、Elasticsearch 专题 +- [x] 云服务器与负载均衡排查专题 +- [x] 集中日志与监控告警专题 +- [x] Git、SSH、curl、jq 开发工具专题 +- [x] PromQL、LogQL 与告警规则专题 +- [x] Linux 网络、监控日志、Docker/Kubernetes 主手册章节迁移 +- [x] PowerShell 高级、Linux 权限、Shell 脚本、跨平台脚本、Keepalived 章节迁移 +- [x] 下一阶段优化计划 +- [x] 巡检脚本 JSON 输出、统一结构和明确退出码 +- [ ] 完整手册原文逐章迁移 + +## 安全提醒 + +涉及删除、权限、磁盘、网络和系统服务的命令请先在测试环境验证。特别是 `rm -rf`、`Remove-Item -Recurse -Force`、磁盘格式化、用户权限修改等操作，执行前务必确认路径、目标机器和备份状态。 + +## 让项目更容易被看见 + +建议在 GitHub 仓库的 **About** 区域补充: + +- Description: `Windows PowerShell、Linux、银河麒麟、统信 UOS 常用命令中文速查手册` +- Topics: `powershell`, `linux`, `windows`, `kylin`, `uos`, `devops`, `sysadmin`, `command-line`, `cheatsheet`, `chinese` +- Website: 启用 GitHub Pages 后可填写 `https://shiwenxin123.github.io/PowerShell-Linux-/` + +## 贡献 + +欢迎补充命令、修正文档、增加真实场景示例。提交前请阅读 [贡献指南](CONTRIBUTING.md)，也可以直接 [创建 Issue](https://github.com/shiwenxin123/PowerShell-Linux-/issues/new/choose)。 + +## 更新日志 + +查看 [CHANGELOG.md](CHANGELOG.md) 了解版本变化。 + +## License + +本项目使用 [MIT License](LICENSE)。 diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..8c72296 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,24 @@ +# Roadmap + +这个路线图用于说明项目后续扩展方向，方便贡献者选择任务。 + +## 近期 + +- 完成主手册剩余章节收口: Kylin/UOS 细节、内核参数、limits、I/O 调优、企业级日志配置。 +- 巡检脚本补 JSON 输出、统一字段和更明确的退出码。 +- 继续扩展真实故障案例库，增加网关超时、消息队列连接失败、数据库连接池耗尽、Kubernetes DNS 异常。 +- 将高危命令风险等级继续回填到具体专题页。 + +## 中期 + +- 优化 GitHub Pages 文档站路线入口: 新手路线、运维路线、国产 Linux 路线、Kubernetes 路线。 +- 增加离线 PDF 发布流程。 +- 增加更多国产 Linux 真实版本案例和离线源目录示例。 +- 增加 Prometheus/Grafana/Loki 真实告警案例。 + +## 长期 + +- 将根目录主手册收口为总目录和历史完整版本说明。 +- 建立版本化发布节奏。 +- 创建 good first issue 任务池。 +- 形成中文运维命令知识库。 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..e5c6ec2 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,21 @@ +# 安全策略 + +这个项目主要是命令文档和示例脚本，但仍然可能涉及删除、权限、磁盘、网络和系统服务等高风险操作。 + +## 报告安全问题 + +如果你发现文档中存在明显危险、误导或可能导致数据损坏的命令，请提交 Issue，并在标题中标注 `[安全]`。 + +请尽量包含: + +- 问题命令 +- 风险说明 +- 影响范围 +- 更安全的替代写法 + +## 文档安全原则 + +- 高危命令必须标注风险。 +- 示例命令避免使用真实公网 IP、密码、Token、内网域名。 +- 删除、格式化、权限递归修改等操作应提供预检查命令。 +- 示例脚本默认不应直接修改系统配置或删除业务文件。 diff --git a/Windows-PowerShell-Linux-Command-Manual.md b/Windows-PowerShell-Linux-Command-Manual.md index fa1a371..a09bc6a 100644 --- a/Windows-PowerShell-Linux-Command-Manual.md +++ b/Windows-PowerShell-Linux-Command-Manual.md @@ -3,6 +3,12 @@ > 版本: 2.0 > 最后更新: 2026-03-13 > 说明: 包含详细命令注释、高级用法与最佳实践，新增银河麒麟、统信 UOS 专用命令与专业运维内容 +> +> 项目导航: [README](README.md) | [命令速查表](docs/COMMAND-CHEATSHEET.md) | [PowerShell/Bash 对照](docs/POWERSHELL-BASH-COMPARISON.md) | [Linux 排障清单](docs/troubleshooting/LINUX-INCIDENT-CHECKLIST.md) | [贡献指南](CONTRIBUTING.md) +> +> 安全提醒: 删除、格式化、权限修改、服务重启等命令可能影响系统或数据。执行 `rm -rf`、`Remove-Item -Recurse -Force`、`chmod -R`、`chown -R`、`mkfs`、`dd` 等命令前，请先确认目标路径、备份和执行环境。 +> +> 风险等级说明: 高危命令请参考 [命令风险等级说明](docs/security/RISK-LEVELS.md)，后续贡献命令时建议统一标注风险等级、执行前检查和回滚建议。 --- @@ -569,6 +575,7 @@ rm file.txt rm -f file.txt # 删除目录及其所有内容 +# 高危操作: 执行前先用 ls dir 确认目标目录 rm -rf dir # 创建文件链接(硬链接) @@ -1687,7 +1694,7 @@ console.log('完成!'); ### 三、跨平台工具推荐 | 工具 | 描述 | Windows | Linux | macOS | -|------|------|---------|-------|-------| +| --- | --- | --- | --- | --- | | Git | 版本控制 | ✅ | ✅ | ✅ | | VS Code | 代码编辑器 | ✅ | ✅ | ✅ | | Docker | 容器化 | ✅ | ✅ | ✅ | @@ -3082,6 +3089,7 @@ kubectl uncordon ### A. 常用快捷键 #### Bash/Shell 快捷键 + - `Ctrl + A`: 移到行首 - `Ctrl + E`: 移到行尾 - `Ctrl + U`: 删除到行首 @@ -3094,6 +3102,7 @@ kubectl uncordon - `Tab`: 自动补全 #### PowerShell 快捷键 + - `Ctrl + A`: 全选 - `Ctrl + C`: 复制/终止 - `Ctrl + V`: 粘贴 @@ -3104,11 +3113,11 @@ kubectl uncordon ### B. 参考资源 -- PowerShell 文档: https://learn.microsoft.com/powershell/ -- Linux 文档: https://www.kernel.org/doc/html/latest/ -- Bash 手册: https://www.gnu.org/software/bash/manual/ -- Linux 命令大全: https://man7.org/linux/man-pages/ +- PowerShell 文档: +- Linux 文档: +- Bash 手册: +- Linux 命令大全: --- -**手册结束** +## 手册结束 diff --git a/docs/COMMAND-CHEATSHEET.md b/docs/COMMAND-CHEATSHEET.md new file mode 100644 index 0000000..caa3f04 --- /dev/null +++ b/docs/COMMAND-CHEATSHEET.md @@ -0,0 +1,91 @@ +# 命令速查表 + +这个页面用于快速查找高频命令。需要完整说明和更多示例时，请查看仓库根目录中的完整手册: [Windows-PowerShell-Linux-Command-Manual.md](https://github.com/shiwenxin123/PowerShell-Linux-/blob/main/Windows-PowerShell-Linux-Command-Manual.md)。 + +## PowerShell 与 Linux 常用对照 + +| 场景 | PowerShell | Linux | +| --- | --- | --- | +| 当前路径 | `Get-Location` / `pwd` | `pwd` | +| 切换目录 | `Set-Location C:\Path` / `cd` | `cd /path` | +| 列出文件 | `Get-ChildItem` / `ls` | `ls -la` | +| 查看文件内容 | `Get-Content file.txt` | `cat file.txt` | +| 读取前几行 | `Get-Content file.txt -TotalCount 10` | `head -n 10 file.txt` | +| 读取后几行 | `Get-Content file.txt -Tail 10` | `tail -n 10 file.txt` | +| 实时查看日志 | `Get-Content app.log -Wait` | `tail -f app.log` | +| 复制文件 | `Copy-Item source dest` | `cp source dest` | +| 移动文件 | `Move-Item old new` | `mv old new` | +| 删除文件 | `Remove-Item file.txt` | `rm file.txt` | +| 创建目录 | `New-Item -ItemType Directory demo` | `mkdir demo` | +| 查找文件 | `Get-ChildItem -Recurse -Filter "*.log"` | `find . -name "*.log"` | +| 搜索文本 | `Select-String -Path *.log -Pattern "error"` | `grep -R "error" .` | +| 查看进程 | `Get-Process` | `ps aux` | +| 停止进程 | `Stop-Process -Id 1234` | `kill 1234` | +| 查看服务 | `Get-Service` | `systemctl list-units --type=service` | +| 重启服务 | `Restart-Service nginx` | `sudo systemctl restart nginx` | +| 查看端口 | `Get-NetTCPConnection` | `ss -tulnp` | +| 测试连通 | `Test-Connection example.com` | `ping example.com` | +| 测试端口 | `Test-NetConnection host -Port 443` | `nc -vz host 443` | +| 下载文件 | `Invoke-WebRequest URL -OutFile file` | `curl -L URL -o file` | + +## 高频排查命令 + +### Windows PowerShell + +```powershell +# 查看占用 8080 端口的进程 +Get-NetTCPConnection -LocalPort 8080 | Select-Object LocalAddress,LocalPort,State,OwningProcess + +# 按 CPU 查看进程 +Get-Process | Sort-Object CPU -Descending | Select-Object -First 10 + +# 实时查看日志 +Get-Content .\app.log -Tail 100 -Wait + +# 查找大文件 +Get-ChildItem C:\ -Recurse -ErrorAction SilentlyContinue | + Where-Object Length -gt 100MB | + Sort-Object Length -Descending | + Select-Object FullName,Length -First 20 +``` + +### Linux + +```bash +# 查看系统版本 +cat /etc/os-release + +# 查看资源占用 +top + +# 查看端口监听 +ss -tulnp + +# 查看服务状态 +systemctl status nginx + +# 查看最近日志 +journalctl -xe + +# 查找大文件 +find / -type f -size +100M 2>/dev/null +``` + +## 高危命令提醒 + +| 命令 | 风险 | 建议 | +| --- | --- | --- | +| `rm -rf /path` | 递归强制删除 | 先用 `ls /path` 确认目标，再删除 | +| `Remove-Item -Recurse -Force` | 递归强制删除 | 使用 `-WhatIf` 预览 | +| `chmod -R 777` | 放开权限 | 尽量使用最小权限 | +| `chown -R` | 批量修改属主 | 确认目录边界 | +| `mkfs.*` | 格式化磁盘 | 确认设备名和备份 | +| `dd if=... of=...` | 低级磁盘写入 | 确认 `of` 目标 | + +## 建议继续补充的速查主题 + +- PowerShell 管道与对象处理 +- Bash 文本处理三件套: `grep`、`awk`、`sed` +- `systemctl` 与 Windows 服务对照 +- 防火墙命令对照 +- 国产 Linux 包管理命令对照 diff --git a/docs/COMMAND-COVERAGE-MATRIX.md b/docs/COMMAND-COVERAGE-MATRIX.md new file mode 100644 index 0000000..d9a94c6 --- /dev/null +++ b/docs/COMMAND-COVERAGE-MATRIX.md @@ -0,0 +1,72 @@ +# 命令覆盖矩阵 + +这个矩阵用于判断项目命令覆盖是否足够全面。覆盖等级分为: + +- 完整: 已有独立专题或案例，命令和场景都较完整。 +- 中等: 已有基础命令，但还缺专题化说明或真实案例。 +- 待补: 目前覆盖不足，建议优先补充。 + +## 总览 + +| 领域 | 当前覆盖 | 优先级 | 建议 | +| --- | --- | --- | --- | +| PowerShell 文件/目录/进程/服务 | 完整 | 中 | 继续补远程管理、事件日志、注册表 | +| Linux 基础命令 | 完整 | 中 | 继续补更多文本处理组合 | +| Linux 网络排查 | 中等 | 高 | 继续补 DNS、路由、抓包案例 | +| Linux 存储与磁盘 | 完整 | 中 | 后续补更多真实扩容案例 | +| Linux 包管理 | 完整 | 中 | 后续补更多国产源差异 | +| 权限与安全 | 完整 | 中 | 后续补更多等保基线案例 | +| 日志与审计 | 完整 | 中 | 后续补集中日志和告警案例 | +| Windows 系统管理 | 完整 | 中 | 后续补更多远程管理案例 | +| 容器与 Kubernetes | 完整 | 中 | 后续补更多 Helm/Ingress/PVC 案例 | +| 国产 Linux | 完整 | 中 | 后续补更多真实版本案例 | +| 数据库与中间件 | 完整 | 中 | 后续补更多真实故障案例 | +| 自动化脚本 | 完整 | 中 | 后续补测试用例、JSON schema 和更多模块 | +| Git 与开发工具 | 完整 | 中 | 后续补更多 GitHub CLI 和调试工具 | +| 云服务器常用排查 | 完整 | 中 | 后续补不同云厂商差异 | +| 集中日志与监控告警 | 完整 | 中 | 后续补更多真实告警案例 | + +## 必补命令族 + +### PowerShell/Windows + +- 事件日志: `Get-EventLog`、`Get-WinEvent` +- 注册表: `Get-ItemProperty`、`Set-ItemProperty` +- 计划任务: `Get-ScheduledTask`、`Start-ScheduledTask` +- 防火墙: `Get-NetFirewallRule`、`New-NetFirewallRule` +- 远程管理: `Enter-PSSession`、`Invoke-Command` +- 软件包: `winget`、`choco`、`Install-Module` + +### Linux 基础与运维 + +- 包管理: `apt`、`dpkg`、`yum`、`dnf`、`rpm` +- 压缩归档: `tar`、`gzip`、`zip`、`unzip` +- 磁盘挂载: `lsblk`、`blkid`、`mount`、`umount`、`fstab` +- LVM: `pvs`、`vgs`、`lvs`、`lvextend` +- 文件句柄: `lsof`、`fuser` +- 抓包: `tcpdump` +- 防火墙: `firewall-cmd`、`ufw`、`iptables`、`nft` +- 安全策略: `getenforce`、`setenforce`、`sestatus` + +### 容器与 Kubernetes + +- Docker Compose: `docker compose ps`、`logs`、`config`、`up`、`down` +- Kubernetes 网络: `kubectl get svc`、`endpoints`、`ingress` +- Kubernetes 存储: `kubectl get pvc`、`pv`、`storageclass` +- Helm: `helm list`、`helm status`、`helm rollback` +- 节点排查: `kubectl describe node`、`kubectl top node` + +### 数据库与中间件 + +- MySQL: `mysqladmin`、`SHOW PROCESSLIST`、`SHOW SLAVE STATUS` +- Redis: `redis-cli info`、`slowlog`、`monitor` +- Nginx: `nginx -t`、`nginx -T`、访问日志分析 +- 消息队列: RabbitMQ、Kafka 基础排查命令 + +## 推荐补充顺序 + +1. 将主手册相关章节迁移到专题目录。 +2. 增加更多真实生产案例。 +3. 新增不同云厂商差异说明。 +4. 新增 GitHub CLI、OpenSSL、nmap 等排障工具专题。 +5. 开始主手册原文逐章迁移。 diff --git a/docs/COMMAND-INDEX.md b/docs/COMMAND-INDEX.md new file mode 100644 index 0000000..65015b8 --- /dev/null +++ b/docs/COMMAND-INDEX.md @@ -0,0 +1,188 @@ +# 命令索引 + +这个索引用于按关键词快速定位常用命令。需要更完整的说明时，可以继续查看仓库根目录中的 [完整手册](https://github.com/shiwenxin123/PowerShell-Linux-/blob/main/Windows-PowerShell-Linux-Command-Manual.md)。 + +## 文件与目录 + +| 命令 | 平台 | 场景 | +| --- | --- | --- | +| `Get-ChildItem` | PowerShell | 列出文件、筛选文件、递归查找 | +| `Get-Content` | PowerShell | 查看文件、实时查看日志 | +| `Copy-Item` | PowerShell | 复制文件或目录 | +| `Move-Item` | PowerShell | 移动或重命名 | +| `Remove-Item` | PowerShell | 删除文件或目录 | +| `ls` | Linux | 列出目录内容 | +| `find` | Linux | 查找文件 | +| `grep` | Linux | 搜索文本 | +| `cp` | Linux | 复制文件或目录 | +| `mv` | Linux | 移动或重命名 | +| `rm` | Linux | 删除文件或目录 | + +## 系统信息 + +| 命令 | 平台 | 场景 | +| --- | --- | --- | +| `Get-ComputerInfo` | PowerShell | 查看 Windows 系统信息 | +| `Get-Process` | PowerShell | 查看进程 | +| `Get-Service` | PowerShell | 查看服务 | +| `Get-PSDrive` | PowerShell | 查看磁盘和驱动器 | +| `uname` | Linux | 查看内核和架构 | +| `cat /etc/os-release` | Linux | 查看发行版信息 | +| `free` | Linux | 查看内存 | +| `df` | Linux | 查看磁盘空间 | +| `du` | Linux | 查看目录占用 | +| `top` | Linux | 实时查看资源 | +| `htop` | Linux | 交互式查看资源 | +| `lscpu` | Linux | 查看 CPU 信息 | +| `lsblk` | Linux | 查看块设备 | +| `uptime` | Linux | 查看运行时间和负载 | + +## 包管理 + +| 命令 | 平台 | 场景 | +| --- | --- | --- | +| `apt` | Debian/UOS | 安装、更新、搜索软件包 | +| `dpkg` | Debian/UOS | 查询和安装 `.deb` 包 | +| `yum` | RHEL/Kylin | 安装、更新、搜索软件包 | +| `dnf` | RHEL/Fedora | 新版 RPM 系包管理 | +| `rpm` | RPM 系 | 查询和安装 `.rpm` 包 | +| `winget` | Windows | Windows 软件包管理 | +| `Install-Module` | PowerShell | 安装 PowerShell 模块 | + +## 网络 + +| 命令 | 平台 | 场景 | +| --- | --- | --- | +| `Test-Connection` | PowerShell | Ping 测试 | +| `Test-NetConnection` | PowerShell | 测试端口 | +| `Get-NetTCPConnection` | PowerShell | 查看 TCP 连接 | +| `ipconfig` | Windows | 查看网络配置 | +| `ping` | Linux | 测试连通性 | +| `ip addr` | Linux | 查看 IP | +| `ip route` | Linux | 查看路由 | +| `ss` | Linux | 查看端口和连接 | +| `curl` | Linux/Windows | HTTP 请求测试 | +| `nc` | Linux | 端口连通测试 | +| `traceroute` | Linux | 路由跟踪 | +| `mtr` | Linux | 连通性和丢包分析 | +| `tcpdump` | Linux | 抓包分析 | +| `nslookup` | Windows/Linux | DNS 查询 | +| `dig` | Linux | DNS 详细查询 | + +## 服务与日志 + +| 命令 | 平台 | 场景 | +| --- | --- | --- | +| `Start-Service` | PowerShell | 启动服务 | +| `Stop-Service` | PowerShell | 停止服务 | +| `Restart-Service` | PowerShell | 重启服务 | +| `systemctl` | Linux | 管理 systemd 服务 | +| `journalctl` | Linux | 查看 systemd 日志 | +| `tail -f` | Linux | 实时查看日志 | +| `Get-WinEvent` | PowerShell | 查看 Windows 事件日志 | +| `Get-EventLog` | PowerShell | 查看传统 Windows 日志 | +| `logrotate` | Linux | 日志轮转 | +| `rsyslogd` | Linux | 系统日志服务 | + +## 权限与用户 + +| 命令 | 平台 | 场景 | +| --- | --- | --- | +| `whoami` | Windows/Linux | 查看当前用户 | +| `sudo` | Linux | 提权执行 | +| `su` | Linux | 切换用户 | +| `useradd` | Linux | 创建用户 | +| `passwd` | Linux | 修改密码 | +| `chmod` | Linux | 修改权限 | +| `chown` | Linux | 修改属主 | +| `sudo -l` | Linux | 查看 sudo 权限 | +| `visudo` | Linux | 安全编辑 sudoers | +| `getenforce` | Linux | 查看 SELinux 状态 | +| `setenforce` | Linux | 临时调整 SELinux 模式 | + +## 磁盘、挂载与归档 + +| 命令 | 平台 | 场景 | +| --- | --- | --- | +| `mount` | Linux | 挂载文件系统 | +| `umount` | Linux | 卸载文件系统 | +| `blkid` | Linux | 查看块设备 UUID | +| `fdisk` | Linux | 查看和管理分区 | +| `parted` | Linux | 分区管理 | +| `pvs` | Linux | 查看 LVM 物理卷 | +| `vgs` | Linux | 查看 LVM 卷组 | +| `lvs` | Linux | 查看 LVM 逻辑卷 | +| `lvextend` | Linux | 扩展逻辑卷 | +| `tar` | Linux | 打包归档 | +| `gzip` | Linux | 压缩文件 | +| `zip` | Windows/Linux | ZIP 压缩 | +| `unzip` | Windows/Linux | ZIP 解压 | + +## Windows 管理 + +| 命令 | 平台 | 场景 | +| --- | --- | --- | +| `Get-ItemProperty` | PowerShell | 读取注册表或对象属性 | +| `Set-ItemProperty` | PowerShell | 修改注册表或对象属性 | +| `Get-ScheduledTask` | PowerShell | 查看计划任务 | +| `Start-ScheduledTask` | PowerShell | 启动计划任务 | +| `Get-NetFirewallRule` | PowerShell | 查看防火墙规则 | +| `New-NetFirewallRule` | PowerShell | 新增防火墙规则 | +| `Enter-PSSession` | PowerShell | 进入远程会话 | +| `Invoke-Command` | PowerShell | 远程执行命令 | + +## 容器与集群 + +| 命令 | 平台 | 场景 | +| --- | --- | --- | +| `docker ps` | Linux/Windows | 查看容器 | +| `docker logs` | Linux/Windows | 查看容器日志 | +| `docker exec` | Linux/Windows | 进入容器执行命令 | +| `kubectl get pods` | Kubernetes | 查看 Pod | +| `kubectl logs` | Kubernetes | 查看 Pod 日志 | +| `kubectl describe` | Kubernetes | 查看资源详情 | +| `kubectl rollout` | Kubernetes | 发布与回滚 | +| `docker compose ps` | Docker | 查看 Compose 服务 | +| `docker compose logs` | Docker | 查看 Compose 日志 | +| `kubectl get svc` | Kubernetes | 查看 Service | +| `kubectl get ingress` | Kubernetes | 查看 Ingress | +| `kubectl get pvc` | Kubernetes | 查看持久卷声明 | +| `helm list` | Kubernetes | 查看 Helm Release | +| `helm rollback` | Kubernetes | 回滚 Helm Release | + +## 数据库与中间件 + +| 命令 | 平台 | 场景 | +| --- | --- | --- | +| `mysqladmin` | MySQL | 查看状态和管理 MySQL | +| `mysql` | MySQL | 执行 SQL 和排查连接 | +| `redis-cli` | Redis | Redis 连接和状态排查 | +| `nginx -t` | Nginx | 检查 Nginx 配置 | +| `nginx -T` | Nginx | 输出完整 Nginx 配置 | +| `psql` | PostgreSQL | PostgreSQL 连接和 SQL 排查 | +| `mongosh` | MongoDB | MongoDB 连接和状态排查 | +| `curl _cluster/health` | Elasticsearch | 查看 Elasticsearch 集群健康 | + +## 开发与排障工具 + +| 命令 | 平台 | 场景 | +| --- | --- | --- | +| `git status` | Git | 查看工作区状态 | +| `git diff` | Git | 查看差异 | +| `git log` | Git | 查看提交历史 | +| `git show` | Git | 查看提交详情 | +| `ssh-keygen` | Windows/Linux | 生成 SSH key | +| `ssh -T` | Windows/Linux | 测试 SSH 认证 | +| `curl -I` | Windows/Linux | 查看 HTTP 响应头 | +| `curl -v` | Windows/Linux | 查看连接细节 | +| `jq` | Windows/Linux | 解析和过滤 JSON | + +## 监控与日志查询 + +| 命令/表达式 | 平台 | 场景 | +| --- | --- | --- | +| `up` | PromQL | 查看 target 是否在线 | +| `rate(metric[5m])` | PromQL | 计算速率 | +| `histogram_quantile` | PromQL | 计算分位延迟 | +| `{app="name"} \|= "error"` | LogQL | 查询错误日志 | +| `count_over_time` | LogQL | 统计日志数量 | diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..95ddaba --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,67 @@ +# FAQ + +## 这个项目适合谁使用？ + +适合正在学习 PowerShell 或 Linux 的用户，也适合需要维护 Windows、Linux、银河麒麟、统信 UOS、Docker、Kubernetes 和常见中间件的开发者、运维人员和值班团队。 + +如果只是临时查命令，可以从 [命令索引](COMMAND-INDEX.md) 或 [命令速查表](COMMAND-CHEATSHEET.md) 开始。如果要系统学习，建议从 [专题化手册](manual/README.md) 进入。 + +## 应该先看主手册还是专题页？ + +优先看专题页。专题页已经按 PowerShell、Linux、国产 Linux、安全、容器、数据库、监控和故障案例拆分，阅读和维护都更清晰。 + +根目录主手册仍保留完整历史内容，后续会继续收口为总目录和历史说明。 + +## 怎么快速找到某个命令？ + +推荐顺序： + +1. 在 GitHub 或文档站搜索命令名。 +2. 查 [命令索引](COMMAND-INDEX.md)。 +3. 查 [命令覆盖矩阵](COMMAND-COVERAGE-MATRIX.md)，确认该领域是否已经覆盖。 +4. 如果是故障场景，优先看 [真实故障案例库](cases/README.md) 和 [常见报错排查](troubleshooting/COMMON-ERRORS.md)。 + +## 文档里的命令可以直接复制执行吗？ + +不要无脑复制执行。涉及删除、格式化、权限递归修改、服务重启、防火墙、磁盘、用户和证书的命令，都应该先确认目标环境、路径、备份和回滚方式。 + +高风险命令建议先阅读 [命令风险等级说明](security/RISK-LEVELS.md)。 + +## Linux 和 Windows 巡检脚本能做什么？ + +巡检脚本用于快速收集系统、磁盘、网络、服务和进程信息。脚本支持 `text`、`markdown` 和 `json` 输出，适合终端查看、工单粘贴和自动化平台消费。 + +详细用法见 [巡检脚本工具化](manual/automation/HEALTH-CHECK-SCRIPTS.md)。JSON 输出字段契约见 [Health Check Report JSON Schema](schema/health-check-report.schema.json)。 + +## 生成的巡检报告可以直接公开吗？ + +不建议直接公开。巡检报告可能包含主机名、IP、端口、进程名、服务名、磁盘路径等信息。公开分享前应先脱敏。 + +项目中的 [Linux JSON 示例](examples/linux-health-check.sample.json) 和 [Windows JSON 示例](examples/windows-health-check.sample.json) 已使用示例化内容。 + +## 如何贡献内容？ + +可以补命令、修正文档、增加故障案例、扩展脚本模块或完善风险说明。提交前请阅读 [贡献指南](https://github.com/shiwenxin123/PowerShell-Linux-/blob/main/CONTRIBUTING.md)。 + +建议优先贡献小而清晰的内容，例如： + +- 补充一个命令的常见用法。 +- 增加一个真实故障案例。 +- 给高危命令补充风险提示。 +- 修复错别字、断链或过时参数。 + +## 维护者发布前应该检查什么？ + +发布前建议按 [Release 检查清单](RELEASE-CHECKLIST.md) 执行，至少确认： + +- 文档检查通过。 +- MkDocs 严格构建通过。 +- 新增链接没有断链。 +- 新增脚本通过对应 CI。 +- `CHANGELOG.md` 已记录变更。 + +## GitHub Pages 文档站如何更新？ + +推送到 `main` 或 `master` 后，会触发 Docs Site 工作流。工作流会安装 `requirements.txt` 中的依赖并执行 `mkdocs build --strict`，然后部署到 GitHub Pages。 + +如果 Pages 构建失败，优先检查 `mkdocs.yml` 导航路径、Markdown 代码块闭合、文件名大小写和依赖版本范围。 diff --git a/docs/GITHUB-GROWTH-CHECKLIST.md b/docs/GITHUB-GROWTH-CHECKLIST.md new file mode 100644 index 0000000..65fc0ee --- /dev/null +++ b/docs/GITHUB-GROWTH-CHECKLIST.md @@ -0,0 +1,111 @@ +# GitHub 热度优化清单 + +这个项目的优势是中文、跨平台、运维实用、覆盖国产 Linux。要获得更多 Star，核心不是堆更多命令，而是让用户在 10 秒内明白: 这个仓库能帮我快速解决命令查询和系统运维问题。 + +## 仓库基础设置 + +- 仓库名建议: `powershell-linux-command-manual` 或 `PowerShell-Linux-Command-Manual` +- Description 建议: `Windows PowerShell、Linux、银河麒麟、统信 UOS 常用命令中文速查手册` +- Topics 建议: + - `powershell` + - `linux` + - `windows` + - `kylin` + - `uos` + - `devops` + - `sysadmin` + - `command-line` + - `cheatsheet` + - `chinese` + +## README 优化重点 + +- 第一屏说明项目解决什么问题。 +- 给出“快速入口”，让用户不用翻 3000 行文档。 +- 明确适合人群: 新手、运维、国产系统用户、跨平台开发者。 +- 放出内容规划，让访问者知道项目还在维护。 +- 鼓励 Issue 和 PR，降低贡献门槛。 + +## 内容继续扩展方向 + +优先补这些，因为它们更容易被搜索和收藏: + +1. PowerShell 与 Bash 命令对照表 +2. Linux 常见报错排查，比如端口占用、权限不足、服务启动失败 +3. 国产 Linux 专区: 麒麟、UOS 的包管理、系统信息、服务管理 +4. 运维应急场景: CPU 飙高、磁盘满、日志爆量、连接失败 +5. 高危命令风险等级: 删除、权限、磁盘、用户、网络 +6. 可复制脚本: 日志清理、端口检查、系统巡检 + +## 推荐目录结构 + +```text +. +├── README.md +├── Windows-PowerShell-Linux-Command-Manual.md +├── CONTRIBUTING.md +├── LICENSE +├── ROADMAP.md +├── CHANGELOG.md +├── SECURITY.md +├── mkdocs.yml +├── docs/ +│ ├── index.md +│ ├── COMMAND-CHEATSHEET.md +│ ├── POWERSHELL-BASH-COMPARISON.md +│ ├── GITHUB-GROWTH-CHECKLIST.md +│ ├── domestic-linux/ +│ └── troubleshooting/ +├── scripts/ +└── .github/ + ├── ISSUE_TEMPLATE/ + └── workflows/ +``` + +后续内容变多以后，可以继续拆分: + +```text +docs/ +├── powershell/ +├── linux/ +├── kylin/ +├── uos/ +├── security/ +└── troubleshooting/ +``` + +## 发布节奏建议 + +- 第 1 周: 补齐 README、License、贡献指南、Issue 模板。 +- 第 2 周: 拆出命令速查表和 PowerShell/Linux 对照表。 +- 第 3 周: 增加“常见故障排查”专题。 +- 第 4 周: 开启 GitHub Pages，做成在线文档站。 + +当前已完成: + +- README 项目首页 +- 命令速查表 +- PowerShell 与 Bash 命令对照 +- Linux 故障应急排查清单 +- 银河麒麟与统信 UOS 专题 +- 示例巡检脚本目录 +- 贡献指南、License、Issue 模板、PR 模板 +- MkDocs 文档站配置和 GitHub Pages 发布工作流 + +## 推广建议 + +- 在 README 顶部放一句明确定位，不要只写“命令手册”。 +- 在掘金、CSDN、知乎、V2EX、开源中国发一篇介绍文章。 +- 标题可以用: `我整理了一份 Windows PowerShell 与 Linux 中文命令速查手册` +- 每次新增一个专题就发 release，比如 `v2.1: 新增 Linux 故障排查命令` +- 将项目提交到中文开源项目集合或 awesome 列表。 + +## 衡量指标 + +- README 是否能让人 10 秒内知道项目价值 +- 是否有稳定更新记录 +- 是否有清晰目录和快速入口 +- 是否有可复制的场景命令 +- 是否方便别人提 Issue 和 PR + +先让项目“看起来值得收藏”，再持续补真实场景，这是最稳的增长方式。 diff --git a/docs/GOOD-FIRST-ISSUES.md b/docs/GOOD-FIRST-ISSUES.md new file mode 100644 index 0000000..36b607f --- /dev/null +++ b/docs/GOOD-FIRST-ISSUES.md @@ -0,0 +1,50 @@ +# Good First Issues 清单 + +这份清单用于维护者批量创建适合新贡献者参与的 GitHub Issues。每个 Issue 都应尽量小、边界清晰，并附上建议修改位置。 + +## 文档类 + +| Issue 标题 | 建议标签 | 建议修改位置 | +| --- | --- | --- | +| 补充网关超时排查案例 | `documentation`, `troubleshooting`, `good first issue` | `docs/cases/` | +| 补充云负载均衡健康检查失败案例 | `documentation`, `cloud`, `good first issue` | `docs/cases/` | +| 补充 Kylin/UOS 不同版本命令差异 | `documentation`, `kylin`, `uos`, `good first issue` | `docs/domestic-linux/` | +| 将主手册附录整理为专题入口 | `documentation`, `manual-migration`, `good first issue` | `docs/MANUAL-MIGRATION.md`、`docs/manual/README.md` | +| 给重点专题页增加相关案例链接 | `documentation`, `good first issue` | `docs/manual/` | + +## 脚本类 + +| Issue 标题 | 建议标签 | 建议修改位置 | +| --- | --- | --- | +| 为巡检脚本增加 package 模块 | `script`, `linux`, `windows`, `help wanted` | `scripts/`、`docs/manual/automation/` | +| 为巡检脚本增加 security 模块 | `script`, `security`, `help wanted` | `scripts/`、`docs/manual/automation/` | +| 为巡检脚本增加 log 模块 | `script`, `linux`, `windows`, `help wanted` | `scripts/`、`docs/manual/automation/` | +| 增加巡检脚本 JSON Schema 示例说明 | `documentation`, `script`, `good first issue` | `docs/manual/automation/HEALTH-CHECK-SCRIPTS.md` | + +## 生产案例类 + +| Issue 标题 | 建议标签 | 建议修改位置 | +| --- | --- | --- | +| 补充消息队列连接失败排查案例 | `documentation`, `middleware`, `help wanted` | `docs/cases/` | +| 补充数据库连接池耗尽排查案例 | `documentation`, `database`, `help wanted` | `docs/cases/` | +| 补充 Prometheus 告警规则误报案例 | `documentation`, `observability`, `good first issue` | `docs/cases/` | + +## Issue 描述模板 + +```markdown +## 背景 + +当前项目已经有相关专题，但缺少这个具体场景。 + +## 建议修改 + +- 新增或更新文档位置: +- 建议结构: 现象 -> 快速判断 -> 排查命令 -> 处理建议 -> 高危提醒 + +## 验收标准 + +- 文档链接没有断链 +- 命令不包含真实 IP、密码、Token +- 高危操作有提醒 +- `scripts/check-docs.ps1` 通过 +``` diff --git a/docs/MAINTAINER-GUIDE.md b/docs/MAINTAINER-GUIDE.md new file mode 100644 index 0000000..96a2c25 --- /dev/null +++ b/docs/MAINTAINER-GUIDE.md @@ -0,0 +1,63 @@ +# 维护者指南 + +这份文档用于帮助项目维护者持续运营仓库，让项目保持可读、可贡献、可发布。 + +## 每次更新前 + +- 确认新增命令适用平台和版本。 +- 高危命令必须补充风险说明。 +- 示例中不要包含真实 IP、密码、Token、内网域名。 +- 大专题优先放入 `docs/`，不要继续堆到 README。 + +## 推荐发布流程 + +1. 更新文档或脚本。 +2. 更新 `CHANGELOG.md`。 +3. 检查 README 快速入口是否需要新增链接。 +4. 检查 `mkdocs.yml` 是否需要加入导航。 +5. 本地执行 `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\check-docs.ps1`。 +6. 本地执行 `python -m mkdocs build --strict`。 +7. 如更新巡检脚本，确认 GitHub Actions 中的 Script Quality 工作流通过。 +8. 提交 PR 或直接合并。 +9. 发布 GitHub Release。 + +## 依赖维护 + +- `requirements.txt` 使用版本范围，避免 MkDocs 或主题大版本升级导致文档站突然构建失败。 +- 升级 MkDocs、Material for MkDocs 或 `pymdown-extensions` 前，先在分支中执行 `python -m mkdocs build --strict`。 +- 如果上游发布大版本，优先阅读迁移说明，再调整 `requirements.txt` 的版本范围。 +- 不建议在没有构建验证的情况下放宽到无限制版本。 + +## Release 标题建议 + +- `v2.2.0 - 新增命令索引与故障排查专题` +- `v2.3.0 - 新增国产 Linux 运维专题` +- `v2.4.0 - 新增 Docker 与 Kubernetes 速查` + +## 首批可创建的 Issues + +这些 Issue 可以帮助项目显得活跃，也方便其他人参与。更完整的候选任务见 [Good First Issues 清单](GOOD-FIRST-ISSUES.md)。 + +| 标题 | 标签 | +| --- | --- | +| 补充网关超时排查案例 | `documentation`, `troubleshooting`, `good first issue` | +| 补充消息队列连接失败案例 | `documentation`, `middleware`, `help wanted` | +| 补充数据库连接池耗尽案例 | `documentation`, `database`, `help wanted` | +| 为巡检脚本增加 package 模块 | `script`, `linux`, `windows`, `help wanted` | +| 为巡检脚本增加 security 模块 | `script`, `security`, `help wanted` | +| 补充 Kylin/UOS 不同版本命令差异 | `documentation`, `kylin`, `uos`, `good first issue` | +| 将主手册附录整理为专题入口 | `documentation`, `manual-migration`, `good first issue` | + +## README 维护原则 + +- README 只放项目定位、快速入口、路线图摘要和贡献入口。 +- 具体命令放到 `docs/`。 +- 新增专题后，同步更新 README、`docs/index.md`、`mkdocs.yml`。 + +## 文档站维护 + +启用 GitHub Pages 后，推送到 `main` 或 `master` 会触发 `.github/workflows/docs-site.yml`。如果构建失败，优先检查: + +- `mkdocs.yml` 导航路径是否存在。 +- Markdown 代码块是否闭合。 +- 文件名大小写是否与导航一致。 diff --git a/docs/MANUAL-MIGRATION.md b/docs/MANUAL-MIGRATION.md new file mode 100644 index 0000000..9376d95 --- /dev/null +++ b/docs/MANUAL-MIGRATION.md @@ -0,0 +1,41 @@ +# 主手册专题化迁移进度 + +根目录完整手册仍保留为历史完整版本和总参考。专题化迁移的目标是把长文档逐步拆成更易搜索、维护和贡献的页面。 + +## 迁移状态 + +| 主手册章节 | 专题页 | 状态 | +| --- | --- | --- | +| Windows PowerShell 基础导航与文件操作 | [PowerShell 基础命令](manual/powershell/BASIC.md) | 已迁移第一版 | +| Windows PowerShell 系统信息、进程、服务、网络 | [PowerShell 系统管理](manual/powershell/SYSTEM-ADMIN.md) | 已迁移第一版 | +| PowerShell 管道、变量、脚本和错误处理 | [PowerShell 高级技巧](manual/powershell/ADVANCED-SCRIPTING.md) | 已迁移 | +| Linux 基础导航与文件操作 | [Linux 基础命令](manual/linux/BASIC.md) | 已迁移第一版 | +| Linux 用户、组、权限管理 | [Linux 用户、组与权限](manual/linux/USERS-PERMISSIONS.md) | 已迁移 | +| Linux Shell 脚本基础与高级技巧 | [Shell 脚本基础与高级技巧](manual/linux/SHELL-SCRIPTING.md) | 已迁移 | +| Linux 网络相关命令 | [Linux 网络排查](manual/linux/NETWORK.md) | 已迁移 | +| Linux 系统监控与日志 | [Linux 系统监控与日志](manual/linux/MONITORING-LOGS.md) | 已迁移 | +| Linux 包管理 | [Linux 包管理](manual/linux/PACKAGE-MANAGEMENT.md) | 已专题化 | +| Linux 磁盘与存储管理 | [Linux 磁盘、挂载与 LVM](manual/linux/DISK-LVM.md) | 已专题化 | +| 系统性能调优 | [Linux 性能调优](manual/linux/PERFORMANCE-TUNING.md) | 已迁移 | +| Docker 与 Kubernetes 基础 | [Docker 与 Kubernetes 生产级命令](manual/kubernetes/DOCKER-K8S-PRODUCTION.md) | 已迁移 | +| 安全加固 | [系统安全加固](manual/security/HARDENING.md) | 已迁移第一版 | +| 防火墙与 SELinux | [防火墙与 SELinux](manual/security/FIREWALL-SELINUX.md) | 已专题化 | +| Python/Node.js 跨平台脚本完整示例 | [Python 与 Node.js 跨平台脚本](manual/cross-platform/PYTHON-NODE-SCRIPTS.md) | 已迁移 | +| 跨平台脚本与工具 | [跨平台脚本与工具](manual/cross-platform/TOOLS.md) | 已补充工具分类 | +| 银河麒麟与统信 UOS | [银河麒麟与统信 UOS 常用命令](domestic-linux/KYLIN-UOS-COMMANDS.md) | 已补充厂商命令细节 | +| 企业级日志管理 | [日志轮转、审计与系统日志](manual/security/LOGGING-AUDIT.md) | 已补充配置样例 | +| 高可用与 Keepalived | [Keepalived 高可用](manual/ha/KEEPALIVED.md) | 已迁移 | + +## 仍建议继续迁移 + +- Kylin/UOS 不同版本和授权组件的命令差异案例。 +- 性能调优的数据库、中间件和容器场景参数对照。 +- 企业日志接入 Loki、ELK、云日志服务的真实案例。 +- 主手册剩余附录内容的入口化整理。 + +## 迁移原则 + +- 每次迁移一个明确章节，避免一次性大改。 +- 迁移后同步更新 `mkdocs.yml`、`docs/index.md`、`CHANGELOG.md`。 +- 高危命令同步补风险提醒。 +- 原主手册保留链接，直到专题页完全覆盖。 diff --git a/docs/NEXT-STAGE-PLAN.md b/docs/NEXT-STAGE-PLAN.md new file mode 100644 index 0000000..b2f710b --- /dev/null +++ b/docs/NEXT-STAGE-PLAN.md @@ -0,0 +1,92 @@ +# 下一阶段优化计划 + +当前项目已经具备完整的命令手册、专题文档、故障案例、脚本、CI 和文档站配置。后续重点应从“继续堆命令”转向“提高深度、减少重复、提升可用性”。 + +## 第一优先级: 完成主手册收口 + +目标: 根目录主手册不再和专题页长期重复。 + +已完成: + +- 补充 Kylin/UOS 厂商命令细节。 +- 新增 Linux 性能调优专题，迁移内核参数、limits、I/O 调优和网络参数检查。 +- 补充企业级日志管理配置样例。 +- 补充跨平台工具推荐分类。 + +建议继续: + +1. 补充 Kylin/UOS 不同版本和授权组件差异案例。 +2. 补充数据库、中间件和容器场景的性能调优对照。 +3. 迁移或入口化整理主手册附录。 +4. 将根目录主手册压缩为总目录、历史说明和专题入口。 + +主手册最终收口路线: + +1. 确认 `docs/MANUAL-MIGRATION.md` 中所有主章节都有专题入口。 +2. 将主手册附录中的快捷键和参考资源迁入 FAQ 或专题入口页。 +3. 在根目录主手册顶部加入“推荐阅读专题页”的提示。 +4. 最终把根目录主手册改为历史完整版本说明，不再维护重复正文。 + +## 第二优先级: 增强巡检脚本 + +目标: 让脚本从示例变成可复用工具。 + +已完成: + +- JSON 输出。 +- 统一 Linux/Windows JSON 字段。 +- 更明确的退出码。 +- 示例报告。 +- GitHub Actions 基础功能测试，覆盖 JSON 输出、输出文件和参数错误退出码。 +- JSON Schema 文件，便于自动化平台对接和字段校验。 + +建议继续补充: + +| 模块 | 目标 | +| --- | --- | +| `package` | 收集包管理器、软件源、关键包版本和更新状态 | +| `security` | 收集 SSH、防火墙、SELinux/AppArmor、sudo 和审计基础状态 | +| `container` | 收集 Docker、containerd、Kubernetes 节点和 Pod 基础状态 | +| `log` | 收集 journal 占用、关键系统日志和最近错误摘要 | + +## 第三优先级: 补真实生产案例 + +已完成: + +- 新增 Kubernetes DNS 异常排查。 +- 新增 Prometheus Target Down 排查。 +- 新增 Grafana 无数据排查。 + +建议新增: + +- 网关超时。 +- 消息队列连接失败。 +- 数据库连接池耗尽。 +- 云负载均衡健康检查失败。 + +## 第四优先级: 文档站体验 + +已完成: + +- 增加 FAQ 页面，集中说明查命令、使用巡检脚本、风险提示、贡献和发布流程。 +- README 和文档站首页增加学习路线。 +- 案例库增加按症状查找索引。 + +建议优化: + +- 给重点专题页增加“相关案例”。 +- 增加离线 PDF 发布流程。 + +## 第五优先级: 开源运营 + +已完成: + +- README 顶部增加 CI、文档站、脚本质量、敏感信息扫描和 License badges。 +- 新增 `v2.16.0` Release 草案。 +- 新增 Good First Issues 清单。 +- 新增故障案例补充 Issue 模板。 + +建议: + +- 发布 GitHub Release。 +- 将文档站地址填入 GitHub About。 diff --git a/docs/POWERSHELL-BASH-COMPARISON.md b/docs/POWERSHELL-BASH-COMPARISON.md new file mode 100644 index 0000000..d5f461b --- /dev/null +++ b/docs/POWERSHELL-BASH-COMPARISON.md @@ -0,0 +1,62 @@ +# PowerShell 与 Bash 命令对照 + +这份对照表适合经常在 Windows 和 Linux 之间切换的用户。PowerShell 更偏对象管道，Bash 更偏文本管道，很多命令看起来相似，但处理方式不同。 + +## 文件与目录 + +| 场景 | PowerShell | Bash/Linux | +| --- | --- | --- | +| 当前目录 | `Get-Location` | `pwd` | +| 切换目录 | `Set-Location C:\Work` | `cd /work` | +| 列出文件 | `Get-ChildItem` | `ls -la` | +| 创建目录 | `New-Item -ItemType Directory demo` | `mkdir demo` | +| 创建文件 | `New-Item file.txt` | `touch file.txt` | +| 复制文件 | `Copy-Item a.txt b.txt` | `cp a.txt b.txt` | +| 复制目录 | `Copy-Item src dst -Recurse` | `cp -r src dst` | +| 移动/重命名 | `Move-Item old new` | `mv old new` | +| 删除文件 | `Remove-Item file.txt` | `rm file.txt` | +| 删除目录 | `Remove-Item dir -Recurse` | `rm -r dir` | + +## 文本查看与搜索 + +| 场景 | PowerShell | Bash/Linux | +| --- | --- | --- | +| 查看文件 | `Get-Content app.log` | `cat app.log` | +| 查看前 20 行 | `Get-Content app.log -TotalCount 20` | `head -n 20 app.log` | +| 查看后 20 行 | `Get-Content app.log -Tail 20` | `tail -n 20 app.log` | +| 实时看日志 | `Get-Content app.log -Wait` | `tail -f app.log` | +| 搜索文本 | `Select-String -Path *.log -Pattern "error"` | `grep "error" *.log` | +| 递归搜索 | `Select-String -Path **/*.log -Pattern "error"` | `grep -R "error" .` | + +## 进程、端口与服务 + +| 场景 | PowerShell | Bash/Linux | +| --- | --- | --- | +| 查看进程 | `Get-Process` | `ps aux` | +| 查找进程 | `Get-Process nginx` | `pgrep -a nginx` | +| 停止进程 | `Stop-Process -Id 1234` | `kill 1234` | +| 强制停止 | `Stop-Process -Id 1234 -Force` | `kill -9 1234` | +| 查看 TCP 连接 | `Get-NetTCPConnection` | `ss -tan` | +| 查看监听端口 | `Get-NetTCPConnection -State Listen` | `ss -tulnp` | +| 查看服务 | `Get-Service` | `systemctl list-units --type=service` | +| 重启服务 | `Restart-Service nginx` | `sudo systemctl restart nginx` | + +## 管道差异 + +PowerShell 管道传递的是对象: + +```powershell +Get-Process | Sort-Object CPU -Descending | Select-Object -First 5 Name,CPU +``` + +Bash 管道传递的是文本: + +```bash +ps aux --sort=-%cpu | head -n 6 +``` + +## 安全建议 + +- PowerShell 删除前可以先加 `-WhatIf` 预览。 +- Linux 删除前先用 `ls` 或 `find` 确认范围。 +- 批量操作时优先在测试目录验证。 diff --git a/docs/PROJECT-AUDIT.md b/docs/PROJECT-AUDIT.md new file mode 100644 index 0000000..c3221fc --- /dev/null +++ b/docs/PROJECT-AUDIT.md @@ -0,0 +1,95 @@ +# 项目整体审查报告 + +本报告基于当前仓库结构、README、MkDocs 导航、脚本和专题文档进行审查，用于判断后续还需要补什么、哪些地方需要更新。 + +## 当前优势 + +- 项目定位已经清晰: 中文、跨平台、运维实用、覆盖国产 Linux。 +- README、贡献指南、License、Issue 模板、PR 模板、Roadmap、Changelog 已具备开源项目基本形态。 +- 文档站配置已经具备，MkDocs 导航覆盖主要专题。 +- 内容已经从单一大手册扩展为命令索引、速查表、故障案例、国产 Linux、容器、安全、脚本等多个入口。 +- 已有基础文档检查脚本: `scripts/check-docs.ps1`。 + +## 主要不足 + +### 1. README 第一屏已精简 + +README 的快速入口已精简为主入口，完整导航交给文档站首页。 + +后续建议: + +- README 继续保持项目首页定位。 +- 新增专题优先放入 `docs/index.md` 和 MkDocs 导航。 +- README 只保留最高频入口。 + +### 2. 主手册与专题页仍存在少量重复 + +根目录完整手册的大部分高价值章节已经迁移或专题化，但 Kylin/UOS 原始厂商命令、内核参数、limits、I/O 调优、企业级日志配置样例仍建议继续迁移。 + +建议: + +- 继续按 [主手册专题化迁移进度](MANUAL-MIGRATION.md) 收口。 +- 迁移完成后，根目录主手册改为“总目录 + 历史完整版本说明”。 +- 避免同一命令在多个页面出现不同写法。 + +### 3. GitHub Actions 已增强，仍可继续细化 + +当前已有文档检查、MkDocs 构建、markdownlint、ShellCheck、PSScriptAnalyzer 和 Gitleaks 敏感信息扫描配置。`scripts/check-docs.ps1` 也加入了基础敏感信息模式检查。 + +建议: + +- 根据实际 lint 结果继续调整规则。 +- 给脚本增加测试样例。 + +### 4. 故障案例还可以继续补真实业务场景 + +当前案例已经覆盖基础运维问题，并补充了 Nginx 502/504、MySQL、Redis、Java OOM、Kubernetes ImagePullBackOff、Docker Compose、TLS 证书链不完整等应用层和中间件案例。 + +建议继续补充: + +- 网关超时 +- 消息队列连接失败 +- 数据库连接池耗尽 +- Kubernetes DNS 异常 + +### 5. 国产 Linux 内容还可补真实版本案例 + +目前已有麒麟/UOS 基础命令、离线安装、架构检查和版本差异专题。后续更适合补真实版本案例和离线源目录示例。 + +建议: + +- 增加银河麒麟 V10 实际问题案例。 +- 增加统信 UOS 桌面版/服务器版真实差异案例。 +- 增加 ARM、龙芯、鲲鹏环境的软件包兼容案例。 +- 增加离线源目录结构示例。 + +### 6. 巡检脚本还只是基础版 + +当前脚本已经支持按模块执行，并支持 text、Markdown、JSON 输出，且 Linux/Windows JSON 使用统一结构。 + +建议: + +- 增加基础测试用例。 +- 增加 JSON schema 文件。 +- 后续扩展 package、security、container 等模块。 + +## 下一步优先级 + +1. 完成主手册剩余章节收口: Kylin/UOS 细节、内核参数、limits、I/O 调优、企业级日志配置。 +2. 为巡检脚本补测试用例和 JSON schema。 +3. 补网关超时、消息队列连接失败、数据库连接池耗尽、Kubernetes DNS 异常案例。 +4. 优化文档站路线入口: 新手路线、运维路线、国产 Linux 路线、Kubernetes 路线。 +5. 增加 Release、badges、good first issue，进入开源运营阶段。 + +## 已在本次审查中修复 + +- 修复 README 中 Issue 链接为 GitHub 绝对链接。 +- 新增 `scripts/check-docs.ps1`，用于检查 Markdown 代码块、相对链接和 MkDocs 导航目标。 +- 更新 `.github/workflows/markdown-check.yml`，让 CI 真正执行文档检查，而不是只列出 Markdown 文件。 +- 修复 `docs/RELEASE-CHECKLIST.md` 中的相对链接。 +- 精简 README 第一屏入口。 +- 新增 markdownlint、ShellCheck、PSScriptAnalyzer 配置。 +- 新增 Nginx 502/504、MySQL、Redis、Java OOM 故障案例。 +- 巡检脚本支持模块化检查和 Markdown 报告。 +- 新增 Gitleaks 工作流和基础敏感信息模式扫描。 +- 新增 Kubernetes ImagePullBackOff、Docker Compose、TLS 证书链不完整故障案例。 diff --git a/docs/RELEASE-2.16-DRAFT.md b/docs/RELEASE-2.16-DRAFT.md new file mode 100644 index 0000000..92d58f8 --- /dev/null +++ b/docs/RELEASE-2.16-DRAFT.md @@ -0,0 +1,51 @@ +# v2.16.0 Release 草案 + +这份草案用于发布 GitHub Release 时快速整理文案。正式发布前请先完成 [Release 检查清单](RELEASE-CHECKLIST.md)。 + +## 本次更新 + +- 主手册收口第 1 批，补充 Kylin/UOS 厂商命令、Linux 性能调优、企业日志配置和跨平台工具分类。 +- 巡检脚本工具化，支持统一 JSON 输出、明确退出码、示例报告和 JSON Schema。 +- 增加巡检脚本 GitHub Actions 功能测试，覆盖 Linux/Windows JSON 输出、输出文件和参数错误退出码。 +- 新增 FAQ、README 学习路线、案例库按症状查找索引。 +- 新增 Kubernetes DNS 异常、Prometheus Target Down、Grafana 无数据排查案例。 +- README 增加 CI、文档站、脚本质量、敏感信息扫描和 License badges。 +- `requirements.txt` 增加 MkDocs 相关依赖版本范围。 + +## 推荐阅读 + +- [FAQ](FAQ.md) +- [学习路线](index.md) +- [巡检脚本工具化](manual/automation/HEALTH-CHECK-SCRIPTS.md) +- [真实故障案例库](cases/README.md) +- [Linux 性能调优](manual/linux/PERFORMANCE-TUNING.md) +- [主手册迁移进度](MANUAL-MIGRATION.md) +- [Good First Issues 清单](GOOD-FIRST-ISSUES.md) + +## 发布前确认 + +- `scripts/check-docs.ps1` 通过。 +- `python -m mkdocs build --strict` 通过。 +- GitHub Actions 主要工作流通过。 +- GitHub About 已填写 Description、Topics 和 Website。 +- 新增文件已加入 Git。 + +## GitHub About 建议 + +Description: + +```text +Windows PowerShell、Linux、银河麒麟、统信 UOS 常用命令中文速查手册 +``` + +Topics: + +```text +powershell, linux, windows, kylin, uos, devops, sysadmin, command-line, cheatsheet, chinese, kubernetes, docker +``` + +Website: + +```text +https://shiwenxin123.github.io/PowerShell-Linux-/ +``` diff --git a/docs/RELEASE-CHECKLIST.md b/docs/RELEASE-CHECKLIST.md new file mode 100644 index 0000000..37b8ff3 --- /dev/null +++ b/docs/RELEASE-CHECKLIST.md @@ -0,0 +1,59 @@ +# Release 检查清单 + +发布新版本前，建议按这个清单检查。 + +## 内容检查 + +- [ ] README 快速入口已更新 +- [ ] `docs/index.md` 文档站首页已更新 +- [ ] `mkdocs.yml` 导航已更新 +- [ ] `CHANGELOG.md` 已记录变更 +- [ ] 高危命令已标注风险 +- [ ] 示例命令不包含敏感信息 + +## 文件检查 + +- [ ] Markdown 代码块已闭合 +- [ ] 链接路径正确 +- [ ] 脚本语法已检查 +- [ ] 新增文件已加入 Git +- [ ] `requirements.txt` 版本范围仍可正常构建文档站 + +## 本地验证 + +- [ ] `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\check-docs.ps1` 通过 +- [ ] `python -m mkdocs build --strict` 通过 +- [ ] 如更新 JSON 示例或 Schema，`python -m json.tool` 校验通过 + +## GitHub 设置检查 + +- [ ] About Description 已填写 +- [ ] Topics 已填写 +- [ ] GitHub Pages 已启用 +- [ ] Issue 模板可用 +- [ ] PR 模板可用 +- [ ] GitHub Actions 主要工作流已通过 + +## Release 准备 + +- [ ] 已基于 [v2.16.0 Release 草案](RELEASE-2.16-DRAFT.md) 更新发布文案 +- [ ] 已确认 tag 名称和 Changelog 版本一致 +- [ ] 已确认 README badges 在 GitHub 页面正常显示 +- [ ] 已确认文档站首页和 FAQ 可访问 + +## 发布文案模板 + +```markdown +## 本次更新 + +- 新增 ... +- 修复 ... +- 优化 ... + +## 推荐阅读 + +- [命令索引](COMMAND-INDEX.md) +- [常见报错排查](troubleshooting/COMMON-ERRORS.md) + +欢迎 Star、Issue 和 PR。 +``` diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..8c72296 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,24 @@ +# Roadmap + +这个路线图用于说明项目后续扩展方向，方便贡献者选择任务。 + +## 近期 + +- 完成主手册剩余章节收口: Kylin/UOS 细节、内核参数、limits、I/O 调优、企业级日志配置。 +- 巡检脚本补 JSON 输出、统一字段和更明确的退出码。 +- 继续扩展真实故障案例库，增加网关超时、消息队列连接失败、数据库连接池耗尽、Kubernetes DNS 异常。 +- 将高危命令风险等级继续回填到具体专题页。 + +## 中期 + +- 优化 GitHub Pages 文档站路线入口: 新手路线、运维路线、国产 Linux 路线、Kubernetes 路线。 +- 增加离线 PDF 发布流程。 +- 增加更多国产 Linux 真实版本案例和离线源目录示例。 +- 增加 Prometheus/Grafana/Loki 真实告警案例。 + +## 长期 + +- 将根目录主手册收口为总目录和历史完整版本说明。 +- 建立版本化发布节奏。 +- 创建 good first issue 任务池。 +- 形成中文运维命令知识库。 diff --git a/docs/cases/CERTIFICATE-EXPIRED.md b/docs/cases/CERTIFICATE-EXPIRED.md new file mode 100644 index 0000000..492a71c --- /dev/null +++ b/docs/cases/CERTIFICATE-EXPIRED.md @@ -0,0 +1,59 @@ +# 证书过期排查 + +## 现象 + +- 浏览器提示证书过期。 +- `curl` 提示 certificate has expired。 +- HTTPS 接口调用失败。 +- Nginx、网关或 Ingress 日志出现 TLS 相关错误。 + +## 快速判断 + +```bash +# 查看站点证书时间 +echo | openssl s_client -servername example.com -connect example.com:443 2>/dev/null | openssl x509 -noout -dates +``` + +## 排查命令 + +```bash +# 查看本地证书文件 +openssl x509 -in /path/to/cert.pem -noout -subject -issuer -dates + +# 查看 Nginx 配置中的证书路径 +nginx -T | grep -E "ssl_certificate|ssl_certificate_key" + +# 检查系统时间 +date +timedatectl +``` + +Kubernetes: + +```bash +# 查看 TLS Secret +kubectl get secret -n -o yaml + +# 查看 Ingress +kubectl describe ingress -n +``` + +## 常见原因 + +- 证书确实过期。 +- 新证书已签发但服务未 reload。 +- Nginx/Ingress 配置仍指向旧证书。 +- 系统时间错误。 +- 中间证书链不完整。 + +## 处理建议 + +- 先确认线上正在使用的证书，而不是只看本地文件。 +- 更新证书后执行配置检查。 +- Nginx 场景先 `nginx -t`，再 `systemctl reload nginx`。 +- Kubernetes 场景更新 Secret 后确认 Ingress 控制器是否重新加载。 + +## 高危提醒 + +- 不要删除旧证书后再排查，先备份。 +- 不要在配置未验证时直接重启网关或 Ingress 控制器。 diff --git a/docs/cases/CPU-HIGH.md b/docs/cases/CPU-HIGH.md new file mode 100644 index 0000000..61458d6 --- /dev/null +++ b/docs/cases/CPU-HIGH.md @@ -0,0 +1,45 @@ +# CPU 飙高排查 + +## 现象 + +- 系统响应变慢。 +- 接口超时。 +- 负载升高，`uptime` 中 load average 明显高于 CPU 核数。 + +## 快速判断 + +```bash +uptime +top +ps aux --sort=-%cpu | head -n 10 +``` + +## 排查命令 + +```bash +# 查看进程线程 +ps -T -p + +# 查看进程打开文件 +lsof -p | head + +# 查看进程启动命令 +ps -fp +``` + +Java 服务可继续查看线程栈: + +```bash +jstack | head +``` + +## 处理建议 + +- 先确认高 CPU 进程是否为业务进程、定时任务、备份任务或异常进程。 +- 对业务进程优先收集日志、线程栈、监控截图，再考虑重启。 +- 对未知进程，先确认路径、用户、启动时间，不要直接强杀。 + +## 高危提醒 + +- `kill -9` 会直接终止进程，可能导致未写入数据丢失。 +- 重启服务前确认是否有流量切换、主备切换或告警通知机制。 diff --git a/docs/cases/DISK-FULL.md b/docs/cases/DISK-FULL.md new file mode 100644 index 0000000..d55fe0b --- /dev/null +++ b/docs/cases/DISK-FULL.md @@ -0,0 +1,46 @@ +# 磁盘空间满排查 + +## 现象 + +- 应用写日志失败。 +- 数据库写入失败。 +- 部署时报 `No space left on device`。 +- 服务突然停止或无法启动。 + +## 快速判断 + +先判断是磁盘块空间满，还是 inode 用完。 + +```bash +df -h +df -i +``` + +## 排查命令 + +```bash +# 查看一级目录占用 +du -sh /* 2>/dev/null | sort -h + +# 查看 /var 下目录占用 +du -sh /var/* 2>/dev/null | sort -h + +# 查找大文件 +find / -type f -size +500M 2>/dev/null + +# 查看仍被进程占用的已删除文件 +lsof | grep deleted +``` + +## 处理建议 + +- 优先清理明确可删除的旧日志、临时文件、旧备份。 +- 对日志文件优先使用日志轮转，而不是长期手动删除。 +- 如果删除文件后空间没有释放，检查是否有进程占用已删除文件。 +- 数据库、容器、对象存储、本地上传目录不要直接删除，先确认业务含义。 + +## 高危提醒 + +- 不要直接执行 `rm -rf /var/*`。 +- 不要清理不了解用途的数据库目录。 +- 删除生产日志前，先保留关键排障证据。 diff --git a/docs/cases/DNS-RESOLUTION-FAILED.md b/docs/cases/DNS-RESOLUTION-FAILED.md new file mode 100644 index 0000000..328a723 --- /dev/null +++ b/docs/cases/DNS-RESOLUTION-FAILED.md @@ -0,0 +1,52 @@ +# DNS 解析失败排查 + +## 现象 + +- 可以 Ping IP，但不能访问域名。 +- `curl` 提示 `Could not resolve host`。 +- 应用日志出现 DNS 解析失败。 + +## 快速判断 + +```bash +ping 8.8.8.8 +ping example.com +cat /etc/resolv.conf +``` + +## 排查命令 + +```bash +# 查询 DNS +nslookup example.com +dig example.com + +# 查看 systemd-resolved 状态 +systemctl status systemd-resolved 2>/dev/null + +# 查看路由 +ip route + +# 测试指定 DNS +nslookup example.com 8.8.8.8 +``` + +## 常见原因 + +- DNS 服务器不可达。 +- `/etc/resolv.conf` 配置错误。 +- 内网域名需要特定 DNS。 +- 防火墙拦截 UDP/TCP 53。 +- 容器或 Pod 内 DNS 配置异常。 + +## 处理建议 + +- 先确认 IP 网络是否正常。 +- 再确认 DNS 服务器是否可达。 +- 内网域名不要随意切到公网 DNS。 +- Kubernetes 场景需要检查 CoreDNS 和 Pod DNS 配置。 + +## 高危提醒 + +- 修改 DNS 配置可能影响整台机器的所有域名访问。 +- 生产环境修改前记录原始 `/etc/resolv.conf`。 diff --git a/docs/cases/DOCKER-COMPOSE-FAILED.md b/docs/cases/DOCKER-COMPOSE-FAILED.md new file mode 100644 index 0000000..6dcab08 --- /dev/null +++ b/docs/cases/DOCKER-COMPOSE-FAILED.md @@ -0,0 +1,53 @@ +# Docker Compose 启动失败排查 + +## 现象 + +- `docker compose up -d` 失败。 +- 容器启动后立即退出。 +- 多服务依赖启动顺序异常。 +- 日志中出现端口冲突、环境变量缺失或挂载失败。 + +## 快速判断 + +```bash +docker compose ps +docker compose logs --tail 100 +docker compose config +``` + +## 排查命令 + +```bash +# 查看指定服务日志 +docker compose logs -f + +# 检查端口占用 +ss -tulnp | grep ':8080' + +# 查看容器退出原因 +docker compose ps -a + +# 重新创建服务 +docker compose up -d --force-recreate +``` + +## 常见原因 + +- `compose.yml` 语法错误。 +- `.env` 缺失或变量名不一致。 +- 主机端口被占用。 +- 挂载目录不存在或权限不足。 +- 服务依赖的数据库、Redis、消息队列未就绪。 +- 镜像拉取失败或架构不匹配。 + +## 处理建议 + +- 先执行 `docker compose config` 检查配置渲染结果。 +- 再看具体服务日志，不要只看 compose 总输出。 +- 对依赖服务增加健康检查，而不是只依赖启动顺序。 +- 端口冲突时先确认占用进程用途。 + +## 高危提醒 + +- `docker compose down -v` 会删除 volume，可能造成数据丢失。 +- 生产环境执行重建前确认数据卷和备份。 diff --git a/docs/cases/DOCKER-RESTARTING.md b/docs/cases/DOCKER-RESTARTING.md new file mode 100644 index 0000000..b537df5 --- /dev/null +++ b/docs/cases/DOCKER-RESTARTING.md @@ -0,0 +1,51 @@ +# Docker 容器反复重启排查 + +## 现象 + +- `docker ps` 中容器反复 Restarting。 +- 应用访问失败。 +- 容器日志持续输出错误。 + +## 快速判断 + +```bash +docker ps -a +docker logs --tail 100 +docker inspect +``` + +## 排查命令 + +```bash +# 查看退出码 +docker inspect --format '{{.State.ExitCode}}' + +# 查看重启次数 +docker inspect --format '{{.RestartCount}}' + +# 查看挂载 +docker inspect --format '{{json .Mounts}}' + +# 查看资源 +docker stats +``` + +## 常见原因 + +- 启动命令错误。 +- 配置文件缺失或格式错误。 +- 环境变量缺失。 +- 端口冲突。 +- 挂载目录权限不足。 +- 应用依赖的数据库、Redis、消息队列不可达。 + +## 处理建议 + +- 先看容器日志，确认应用自身报错。 +- 检查镜像版本、环境变量、挂载路径和网络。 +- 临时排查可用 `docker run --rm -it image sh` 进入同镜像环境验证。 + +## 高危提醒 + +- 不要随意删除 volume，可能丢失持久化数据。 +- `docker system prune -a` 会清理大量缓存和镜像，生产环境谨慎执行。 diff --git a/docs/cases/GRAFANA-NO-DATA.md b/docs/cases/GRAFANA-NO-DATA.md new file mode 100644 index 0000000..a9d28b0 --- /dev/null +++ b/docs/cases/GRAFANA-NO-DATA.md @@ -0,0 +1,79 @@ +# Grafana 无数据排查 + +## 现象 + +- Grafana 面板显示 `No data`。 +- 同一数据源部分面板正常，部分面板无数据。 +- 最近发布、迁移或改查询后指标消失。 +- Prometheus、Loki、Elasticsearch 等数据源测试连接成功，但图表为空。 + +## 快速判断 + +```bash +# 检查 Grafana 服务 +systemctl status grafana-server +journalctl -u grafana-server -n 100 --no-pager +``` + +在 Grafana 页面先确认: + +- 时间范围是否正确。 +- 变量是否选中了实际存在的环境、集群、命名空间或实例。 +- 数据源是否选错。 +- 查询语句在 Explore 中是否能返回数据。 + +## 排查命令 + +Prometheus: + +```bash +# Prometheus 是否有数据 +curl -G 'http://prometheus.example.com/api/v1/query' --data-urlencode 'query=up' + +# 检查目标状态 +curl -s http://prometheus.example.com/api/v1/targets +``` + +Loki: + +```bash +# 查询标签 +curl -G 'http://loki.example.com/loki/api/v1/labels' + +# 查询日志 +curl -G 'http://loki.example.com/loki/api/v1/query' --data-urlencode 'query={job!=""}' +``` + +Elasticsearch: + +```bash +# 查看索引 +curl -s http://elasticsearch.example.com:9200/_cat/indices?v + +# 查看集群状态 +curl -s http://elasticsearch.example.com:9200/_cluster/health?pretty +``` + +## 常见原因 + +- Grafana 时间范围选错。 +- Dashboard 变量没有匹配到数据。 +- 查询语句标签名、指标名或日志标签变更。 +- 数据源地址、认证或组织权限配置错误。 +- Prometheus target down，导致指标源头没有采集。 +- Loki/Elasticsearch 索引或日志标签变更。 +- 面板使用的 interval、rate 窗口过小或过大。 + +## 处理建议 + +- 先在 Explore 里运行最小查询，例如 `up` 或 `{job!=""}`。 +- 再逐步加回变量、标签过滤和聚合条件。 +- 如果只有某个 Dashboard 异常，优先检查变量和查询语句。 +- 如果所有面板无数据，优先检查数据源连接、认证和后端采集链路。 +- 对 Prometheus 面板，联动检查 [Prometheus Target Down 排查](PROMETHEUS-TARGET-DOWN.md)。 + +## 高危提醒 + +- 不要直接删除 Dashboard 或数据源，先导出 JSON 备份。 +- 修改共享 Dashboard 变量会影响所有使用者。 +- 为了“让图有数据”而扩大查询范围，可能导致数据源压力升高。 diff --git a/docs/cases/JAVA-OOM.md b/docs/cases/JAVA-OOM.md new file mode 100644 index 0000000..46e7937 --- /dev/null +++ b/docs/cases/JAVA-OOM.md @@ -0,0 +1,59 @@ +# Java 服务 OOM 排查 + +## 现象 + +- Java 服务突然退出。 +- 日志出现 `OutOfMemoryError`。 +- 接口大量超时，进程内存持续升高。 +- 系统日志出现 OOM Killer。 + +## 快速判断 + +```bash +ps aux --sort=-%mem | head -n 10 +dmesg -T | grep -i "out of memory" +journalctl -k | grep -i "killed process" +``` + +## 排查命令 + +```bash +# 查看 Java 进程 +jps -l + +# 查看 JVM 参数 +jcmd VM.flags + +# 查看堆信息 +jcmd GC.heap_info + +# 导出线程栈 +jstack > jstack.txt +``` + +如果服务仍可响应，可以导出堆转储: + +```bash +jmap -dump:format=b,file=heap.hprof +``` + +## 常见原因 + +- JVM 堆设置过小。 +- 内存泄漏。 +- 大对象或大查询结果占用内存。 +- 线程数过多。 +- 容器内存限制小于 JVM 预期。 +- 频繁 Full GC 导致服务不可用。 + +## 处理建议 + +- 先保留日志、GC 日志、线程栈和必要的 heap dump。 +- 容器环境检查内存 limit 和 JVM 参数是否匹配。 +- 结合监控确认内存增长趋势。 +- 临时恢复可以重启服务，但需要继续定位根因。 + +## 高危提醒 + +- `jmap -dump` 可能生成很大的文件，执行前确认磁盘空间。 +- heap dump 可能包含敏感业务数据，传输和分享前要脱敏。 diff --git a/docs/cases/K8S-CRASHLOOPBACKOFF.md b/docs/cases/K8S-CRASHLOOPBACKOFF.md new file mode 100644 index 0000000..b85d934 --- /dev/null +++ b/docs/cases/K8S-CRASHLOOPBACKOFF.md @@ -0,0 +1,59 @@ +# Kubernetes Pod CrashLoopBackOff 排查 + +## 现象 + +- `kubectl get pods` 显示 `CrashLoopBackOff`。 +- Pod 不断重启。 +- 服务不可用或只有部分副本可用。 + +## 快速判断 + +```bash +kubectl get pods -n +kubectl describe pod -n +kubectl logs -n +``` + +多容器 Pod: + +```bash +kubectl logs -c -n +``` + +## 排查命令 + +```bash +# 查看上一次崩溃日志 +kubectl logs -n --previous + +# 查看事件 +kubectl get events -n --sort-by=.lastTimestamp + +# 查看部署配置 +kubectl get deploy -n -o yaml +``` + +## 常见原因 + +- 应用启动失败。 +- 配置文件、环境变量或 Secret 缺失。 +- 镜像版本错误。 +- 探针配置不合理。 +- 依赖服务不可达。 +- 容器内文件权限不正确。 + +## 处理建议 + +- 优先查看 `--previous` 日志。 +- 检查 ConfigMap、Secret、启动命令和探针。 +- 如果新版本发布后出现，查看 rollout 历史并考虑回滚。 + +```bash +kubectl rollout history deploy/ -n +kubectl rollout undo deploy/ -n +``` + +## 高危提醒 + +- 回滚前确认影响范围和当前流量。 +- 不要直接删除生产命名空间资源。 diff --git a/docs/cases/K8S-DNS-FAILED.md b/docs/cases/K8S-DNS-FAILED.md new file mode 100644 index 0000000..60851bf --- /dev/null +++ b/docs/cases/K8S-DNS-FAILED.md @@ -0,0 +1,75 @@ +# Kubernetes DNS 异常排查 + +## 现象 + +- Pod 内访问 Service 名称失败。 +- 应用日志出现 `no such host`、`Name or service not known`。 +- 通过 ClusterIP 可以访问，但通过服务名或域名无法访问。 +- 集群中部分命名空间或部分节点 DNS 异常。 + +## 快速判断 + +```bash +kubectl get pods -n kube-system -l k8s-app=kube-dns +kubectl get svc -n kube-system kube-dns +kubectl get endpoints -n kube-system kube-dns +``` + +进入临时 Pod 测试: + +```bash +kubectl run dns-test --rm -it --image=busybox:1.36 --restart=Never -- nslookup kubernetes.default +``` + +## 排查命令 + +```bash +# 查看 CoreDNS 日志 +kubectl logs -n kube-system deploy/coredns + +# 查看 CoreDNS 配置 +kubectl get configmap coredns -n kube-system -o yaml + +# 查看 kube-dns Service +kubectl describe svc kube-dns -n kube-system + +# 查看 Pod DNS 配置 +kubectl exec -n -- cat /etc/resolv.conf + +# 测试同命名空间 Service +kubectl exec -n -- nslookup + +# 测试完整域名 +kubectl exec -n -- nslookup ..svc.cluster.local + +# 查看事件 +kubectl get events -A --sort-by=.lastTimestamp +``` + +## 常见原因 + +- CoreDNS Pod 未运行或反复重启。 +- CoreDNS ConfigMap 配置错误。 +- kube-dns Service 或 Endpoints 异常。 +- 节点网络、CNI、NetworkPolicy 阻断到 DNS 服务的访问。 +- Pod 的 `dnsPolicy` 或 `dnsConfig` 配置不正确。 +- 上游 DNS 不可达，导致外部域名解析失败。 + +## 处理建议 + +- 先确认 CoreDNS Pod、副本数、Service 和 Endpoints 是否正常。 +- 如果只有外部域名失败，重点检查 CoreDNS 上游 DNS 和节点 `/etc/resolv.conf`。 +- 如果只有某个命名空间失败，检查 NetworkPolicy 和应用 Pod 的 DNS 配置。 +- 修改 CoreDNS 配置前先备份 ConfigMap。 + +```bash +kubectl get configmap coredns -n kube-system -o yaml > coredns.backup.yaml +kubectl rollout restart deploy/coredns -n kube-system +kubectl rollout status deploy/coredns -n kube-system +``` + +## 高危提醒 + +- 不要直接删除 kube-system 中的 DNS 资源。 +- 修改 CoreDNS 配置会影响整个集群解析，生产环境应先在测试集群验证。 +- 重启 CoreDNS 前确认副本数和 PodDisruptionBudget，避免短时间内解析不可用。 diff --git a/docs/cases/K8S-IMAGEPULLBACKOFF.md b/docs/cases/K8S-IMAGEPULLBACKOFF.md new file mode 100644 index 0000000..4465df6 --- /dev/null +++ b/docs/cases/K8S-IMAGEPULLBACKOFF.md @@ -0,0 +1,53 @@ +# Kubernetes ImagePullBackOff 排查 + +## 现象 + +- Pod 状态显示 `ImagePullBackOff` 或 `ErrImagePull`。 +- 新版本发布后 Pod 无法启动。 +- `kubectl describe pod` 事件中出现镜像拉取失败。 + +## 快速判断 + +```bash +kubectl get pods -n +kubectl describe pod -n +``` + +重点查看 Events 中的错误信息。 + +## 排查命令 + +```bash +# 查看 Pod 使用的镜像 +kubectl get pod -n -o jsonpath='{.spec.containers[*].image}' + +# 查看镜像拉取密钥 +kubectl get secret -n + +# 查看 ServiceAccount +kubectl get serviceaccount -n + +# 查看节点是否能访问镜像仓库 +kubectl get nodes -o wide +``` + +## 常见原因 + +- 镜像名称或 tag 写错。 +- 镜像仓库需要认证，但没有配置 `imagePullSecrets`。 +- 节点无法访问镜像仓库。 +- 镜像架构与节点架构不匹配。 +- 私有仓库证书不被节点信任。 +- 镜像被删除或 tag 被覆盖。 + +## 处理建议 + +- 先确认镜像名称、tag 和仓库地址。 +- 私有仓库检查 `imagePullSecrets` 是否在同一 namespace。 +- 多架构环境检查节点架构和镜像架构。 +- 内网环境确认节点到仓库的 DNS、路由、防火墙和证书。 + +## 高危提醒 + +- 不要随意把生产镜像 tag 改成 `latest`。 +- 修复镜像仓库认证时不要把账号密码写进明文 YAML。 diff --git a/docs/cases/MYSQL-START-FAILED.md b/docs/cases/MYSQL-START-FAILED.md new file mode 100644 index 0000000..69f4861 --- /dev/null +++ b/docs/cases/MYSQL-START-FAILED.md @@ -0,0 +1,54 @@ +# MySQL 启动失败排查 + +## 现象 + +- `systemctl start mysql` 或 `systemctl start mysqld` 失败。 +- 应用连接数据库失败。 +- 日志中出现权限、端口、磁盘或配置错误。 + +## 快速判断 + +```bash +systemctl status mysql || systemctl status mysqld +journalctl -u mysql -n 100 --no-pager || journalctl -u mysqld -n 100 --no-pager +``` + +## 排查命令 + +```bash +# 查看 MySQL 错误日志 +tail -n 100 /var/log/mysql/error.log 2>/dev/null +tail -n 100 /var/log/mysqld.log 2>/dev/null + +# 检查端口占用 +ss -tulnp | grep ':3306' + +# 检查磁盘空间 +df -h +df -i + +# 检查数据目录权限 +ls -ld /var/lib/mysql +``` + +## 常见原因 + +- 配置文件语法或参数错误。 +- 3306 端口被占用。 +- 磁盘空间或 inode 用完。 +- 数据目录权限错误。 +- 上次异常退出导致恢复失败。 +- 内存不足或 OOM。 + +## 处理建议 + +- 优先查看 MySQL 错误日志，不要盲目反复启动。 +- 检查磁盘和权限。 +- 配置变更后回滚到最近可用版本验证。 +- 数据目录问题先备份，不要直接删除文件。 + +## 高危提醒 + +- 不要删除 `/var/lib/mysql` 下不认识的文件。 +- 不要在没有备份的情况下执行修复或初始化命令。 +- 生产数据库操作前必须确认备份和恢复方案。 diff --git a/docs/cases/NGINX-502-504.md b/docs/cases/NGINX-502-504.md new file mode 100644 index 0000000..59ce1db --- /dev/null +++ b/docs/cases/NGINX-502-504.md @@ -0,0 +1,57 @@ +# Nginx 502/504 排查 + +## 现象 + +- 页面返回 `502 Bad Gateway`。 +- 页面返回 `504 Gateway Time-out`。 +- Nginx 正常运行，但后端服务不可用或响应慢。 + +## 快速判断 + +```bash +systemctl status nginx +tail -n 100 /var/log/nginx/error.log +curl -I http://127.0.0.1 +``` + +## 排查命令 + +```bash +# 查看 upstream 配置 +nginx -T | grep -n "upstream\\|proxy_pass" + +# 测试后端端口 +nc -vz 127.0.0.1 8080 + +# 查看后端端口监听 +ss -tulnp | grep ':8080' + +# 查看 Nginx 错误日志 +grep -iE "upstream|connect|timeout|refused" /var/log/nginx/error.log | tail -n 50 +``` + +## 常见原因 + +- 后端服务没有启动。 +- 后端端口配置错误。 +- 后端响应超时。 +- Nginx 到后端网络不通。 +- 后端连接数耗尽。 +- 代理超时时间设置过短。 + +## 处理建议 + +- 先确认后端服务是否可直接访问。 +- 再确认 `proxy_pass` 地址、端口和协议是否正确。 +- 如果是 504，重点看后端响应时间、慢查询、线程池和连接池。 +- 修改 Nginx 配置后先执行 `nginx -t`。 + +```bash +nginx -t +systemctl reload nginx +``` + +## 高危提醒 + +- 不要只重启 Nginx，502/504 很多时候根因在后端服务。 +- 修改超时时间只能缓解现象，不能替代后端性能排查。 diff --git a/docs/cases/NGINX-START-FAILED.md b/docs/cases/NGINX-START-FAILED.md new file mode 100644 index 0000000..498dd95 --- /dev/null +++ b/docs/cases/NGINX-START-FAILED.md @@ -0,0 +1,56 @@ +# Nginx 启动失败排查 + +## 现象 + +- `systemctl start nginx` 失败。 +- `systemctl status nginx` 显示 `failed`。 +- 网站访问失败。 +- 日志出现配置错误、端口占用或证书文件错误。 + +## 快速判断 + +```bash +systemctl status nginx +nginx -t +journalctl -u nginx -n 100 --no-pager +``` + +## 排查命令 + +```bash +# 检查端口占用 +ss -tulnp | grep ':80\|:443' + +# 查看 Nginx 配置路径 +nginx -T | head + +# 查看错误日志 +tail -n 100 /var/log/nginx/error.log + +# 检查证书文件是否存在 +ls -l /path/to/cert.pem /path/to/key.pem +``` + +## 常见原因 + +- 配置文件语法错误。 +- 80 或 443 端口被占用。 +- 证书文件路径错误或权限不足。 +- upstream 后端地址不可达。 +- 配置 include 了不存在的文件。 + +## 处理建议 + +- 修改配置后先执行 `nginx -t`，通过后再 reload。 +- 端口冲突时先确认占用进程，不要直接强杀。 +- 证书问题先检查路径、权限和过期时间。 + +```bash +nginx -t +systemctl reload nginx +``` + +## 高危提醒 + +- 不要在配置未通过 `nginx -t` 时重启生产 Nginx。 +- 修改 80/443 端口和证书配置前，确认回滚方案。 diff --git a/docs/cases/PORT-IN-USE.md b/docs/cases/PORT-IN-USE.md new file mode 100644 index 0000000..95fe24f --- /dev/null +++ b/docs/cases/PORT-IN-USE.md @@ -0,0 +1,52 @@ +# 端口被占用排查 + +## 现象 + +- 服务启动失败。 +- 日志出现 `Address already in use`。 +- 本地调试端口无法绑定。 + +## 快速判断 + +Linux: + +```bash +ss -tulnp | grep ':8080' +lsof -i :8080 +``` + +PowerShell: + +```powershell +Get-NetTCPConnection -LocalPort 8080 +``` + +## 排查命令 + +Linux: + +```bash +# 查看进程详情 +ps -fp + +# 查看服务状态 +systemctl status +``` + +PowerShell: + +```powershell +# 根据 PID 查看进程 +Get-Process -Id +``` + +## 处理建议 + +- 如果端口被同一个服务旧进程占用，优先用服务管理命令停止或重启。 +- 如果端口被其他服务占用，修改当前服务端口或调整部署规划。 +- 本地开发场景可以关闭占用进程，但生产环境要先确认进程用途。 + +## 高危提醒 + +- 不要只看到端口占用就直接强杀 PID。 +- SSH、数据库、网关、注册中心等基础服务被误杀会造成更大故障。 diff --git a/docs/cases/PROMETHEUS-TARGET-DOWN.md b/docs/cases/PROMETHEUS-TARGET-DOWN.md new file mode 100644 index 0000000..da67e17 --- /dev/null +++ b/docs/cases/PROMETHEUS-TARGET-DOWN.md @@ -0,0 +1,91 @@ +# Prometheus Target Down 排查 + +## 现象 + +- Prometheus 页面中 Target 状态为 `DOWN`。 +- 告警出现 `TargetDown`、`up == 0`。 +- Grafana 指标断点或某些实例指标消失。 +- Exporter 进程存在，但 Prometheus 抓取失败。 + +## 快速判断 + +```bash +# 查看 Prometheus 服务状态 +systemctl status prometheus + +# 查看 exporter 端口 +ss -tulnp | grep -E '9100|9113|9121|9187|9090' + +# 本机直接访问 exporter +curl -I http://127.0.0.1:9100/metrics +``` + +Kubernetes 环境: + +```bash +kubectl get pods -A | grep -i prometheus +kubectl get servicemonitor,podmonitor -A +kubectl get endpoints -A | grep -i exporter +``` + +## 排查命令 + +```bash +# 查看 Prometheus 配置 +promtool check config /etc/prometheus/prometheus.yml + +# 查看抓取目标配置 +grep -n "job_name\\|targets" /etc/prometheus/prometheus.yml + +# 测试目标连通性 +curl -v http://:/metrics + +# 查看 Prometheus 日志 +journalctl -u prometheus -n 100 --no-pager + +# 查看 exporter 日志 +journalctl -u node_exporter -n 100 --no-pager +``` + +Kubernetes 环境: + +```bash +# 查看 Prometheus Operator 相关资源 +kubectl describe servicemonitor -n +kubectl describe podmonitor -n + +# 查看 Prometheus 日志 +kubectl logs -n + +# 从集群内测试 exporter +kubectl run curl-test --rm -it --image=curlimages/curl --restart=Never -- curl -v http://.:/metrics +``` + +## 常见原因 + +- Exporter 进程未启动或端口未监听。 +- Prometheus 配置中的目标地址、端口或路径错误。 +- 防火墙、安全组、NetworkPolicy 阻断抓取。 +- `/metrics` 路径返回非 200 状态码。 +- ServiceMonitor/PodMonitor 标签选择器不匹配。 +- Prometheus 重新加载配置失败。 +- TLS、Basic Auth 或 Bearer Token 配置不匹配。 + +## 处理建议 + +- 先确认 `curl http://target:port/metrics` 是否能返回指标。 +- 再确认 Prometheus 配置、ServiceMonitor 选择器和目标标签。 +- 修改配置后先用 `promtool check config`。 +- Kubernetes 中优先检查 Service、Endpoints、ServiceMonitor 三者是否匹配。 + +```bash +# 重新加载 Prometheus，视部署方式而定 +curl -X POST http://127.0.0.1:9090/-/reload +systemctl reload prometheus +``` + +## 高危提醒 + +- 不要只关闭告警，应先确认监控缺口是否影响生产发现能力。 +- 修改全局 scrape interval 或 relabel 规则前，评估 Prometheus 负载和指标基数。 +- 生产环境不要随意暴露 `/metrics` 到公网。 diff --git a/docs/cases/README.md b/docs/cases/README.md new file mode 100644 index 0000000..721ec8d --- /dev/null +++ b/docs/cases/README.md @@ -0,0 +1,54 @@ +# 真实故障案例库 + +这里收集高频运维故障的排查路径。每个案例都按“现象 -> 快速判断 -> 排查命令 -> 处理建议 -> 高危提醒”的结构整理，适合值班、培训和应急排障。 + +## 按症状查找 + +| 现象 | 优先查看 | +| --- | --- | +| 页面打不开、网关错误 | [Nginx 502/504](NGINX-502-504.md)、[DNS 解析失败](DNS-RESOLUTION-FAILED.md)、[证书过期](CERTIFICATE-EXPIRED.md)、[TLS 证书链不完整](TLS-CHAIN-INCOMPLETE.md) | +| 服务端口不可用 | [端口被占用](PORT-IN-USE.md)、[Nginx 启动失败](NGINX-START-FAILED.md)、[MySQL 启动失败](MYSQL-START-FAILED.md)、[Redis 连接失败](REDIS-CONNECTION-FAILED.md) | +| 主机资源异常 | [磁盘空间满](DISK-FULL.md)、[CPU 飙高](CPU-HIGH.md)、[Java 服务 OOM](JAVA-OOM.md) | +| 容器或 Pod 异常 | [Docker 容器反复重启](DOCKER-RESTARTING.md)、[Pod CrashLoopBackOff](K8S-CRASHLOOPBACKOFF.md)、[ImagePullBackOff](K8S-IMAGEPULLBACKOFF.md)、[Kubernetes DNS 异常](K8S-DNS-FAILED.md) | +| 监控无数据或告警 | [Prometheus Target Down](PROMETHEUS-TARGET-DOWN.md)、[Grafana 无数据](GRAFANA-NO-DATA.md) | +| 远程登录失败 | [SSH 连接失败](SSH-CONNECTION-FAILED.md)、[DNS 解析失败](DNS-RESOLUTION-FAILED.md)、[端口被占用](PORT-IN-USE.md) | + +## 案例列表 + +| 故障 | 文档 | +| --- | --- | +| 磁盘空间满 | [磁盘空间满排查](DISK-FULL.md) | +| CPU 飙高 | [CPU 飙高排查](CPU-HIGH.md) | +| 端口被占用 | [端口被占用排查](PORT-IN-USE.md) | +| SSH 连接失败 | [SSH 连接失败排查](SSH-CONNECTION-FAILED.md) | +| Nginx 启动失败 | [Nginx 启动失败排查](NGINX-START-FAILED.md) | +| Nginx 502/504 | [Nginx 502/504 排查](NGINX-502-504.md) | +| MySQL 启动失败 | [MySQL 启动失败排查](MYSQL-START-FAILED.md) | +| Redis 连接失败 | [Redis 连接失败排查](REDIS-CONNECTION-FAILED.md) | +| Java 服务 OOM | [Java 服务 OOM 排查](JAVA-OOM.md) | +| DNS 解析失败 | [DNS 解析失败排查](DNS-RESOLUTION-FAILED.md) | +| 证书过期 | [证书过期排查](CERTIFICATE-EXPIRED.md) | +| Docker 容器反复重启 | [Docker 容器反复重启排查](DOCKER-RESTARTING.md) | +| Docker Compose 启动失败 | [Docker Compose 启动失败排查](DOCKER-COMPOSE-FAILED.md) | +| Kubernetes Pod CrashLoopBackOff | [Pod CrashLoopBackOff 排查](K8S-CRASHLOOPBACKOFF.md) | +| Kubernetes ImagePullBackOff | [ImagePullBackOff 排查](K8S-IMAGEPULLBACKOFF.md) | +| Kubernetes DNS 异常 | [Kubernetes DNS 异常排查](K8S-DNS-FAILED.md) | +| TLS 证书链不完整 | [TLS 证书链不完整排查](TLS-CHAIN-INCOMPLETE.md) | +| Prometheus Target Down | [Prometheus Target Down 排查](PROMETHEUS-TARGET-DOWN.md) | +| Grafana 无数据 | [Grafana 无数据排查](GRAFANA-NO-DATA.md) | + +## 案例模板 + +```markdown +# 案例标题 + +## 现象 + +## 快速判断 + +## 排查命令 + +## 处理建议 + +## 高危提醒 +``` diff --git a/docs/cases/REDIS-CONNECTION-FAILED.md b/docs/cases/REDIS-CONNECTION-FAILED.md new file mode 100644 index 0000000..9e64f8b --- /dev/null +++ b/docs/cases/REDIS-CONNECTION-FAILED.md @@ -0,0 +1,51 @@ +# Redis 连接失败排查 + +## 现象 + +- 应用连接 Redis 超时。 +- 提示 `Connection refused`。 +- 提示认证失败。 +- Redis 服务运行但业务读写异常。 + +## 快速判断 + +```bash +systemctl status redis || systemctl status redis-server +ss -tulnp | grep ':6379' +redis-cli ping +``` + +## 排查命令 + +```bash +# 查看 Redis 日志 +journalctl -u redis -n 100 --no-pager 2>/dev/null +journalctl -u redis-server -n 100 --no-pager 2>/dev/null + +# 指定 host 和端口测试 +redis-cli -h 127.0.0.1 -p 6379 ping + +# 查看配置 +grep -E "^(bind|port|requirepass|protected-mode)" /etc/redis/redis.conf 2>/dev/null +``` + +## 常见原因 + +- Redis 服务未启动。 +- 端口未监听或被防火墙拦截。 +- `bind` 只绑定了本地地址。 +- 开启了 `protected-mode`。 +- 密码配置不一致。 +- Redis 内存达到上限。 + +## 处理建议 + +- 先在 Redis 本机用 `redis-cli ping` 验证。 +- 再从应用机器测试网络连通。 +- 检查应用配置中的 host、port、password、database。 +- 生产环境不要为了连通性直接关闭认证。 + +## 高危提醒 + +- Redis 暴露到公网风险极高。 +- 修改 `bind`、`protected-mode`、密码前确认网络边界和访问控制。 diff --git a/docs/cases/SSH-CONNECTION-FAILED.md b/docs/cases/SSH-CONNECTION-FAILED.md new file mode 100644 index 0000000..5d261f5 --- /dev/null +++ b/docs/cases/SSH-CONNECTION-FAILED.md @@ -0,0 +1,51 @@ +# SSH 连接失败排查 + +## 现象 + +- SSH 连接超时。 +- 提示 `Connection refused`。 +- 提示 `Permission denied`。 +- 登录后立刻断开。 + +## 快速判断 + +从客户端开始确认网络、端口和认证。 + +```bash +ping +nc -vz 22 +ssh -vvv user@server +``` + +## 服务端排查 + +```bash +# 查看 SSH 服务 +systemctl status sshd || systemctl status ssh + +# 查看监听端口 +ss -tulnp | grep ':22' + +# 查看认证日志 +journalctl -u sshd -n 100 --no-pager +``` + +## 常见原因 + +- 服务器不可达或安全组未放通。 +- SSH 服务未启动。 +- 防火墙阻断 22 端口。 +- 用户名、密码或密钥错误。 +- `sshd_config` 配置限制登录。 + +## 处理建议 + +- 云服务器先检查安全组和防火墙。 +- 内网服务器先确认路由和堡垒机策略。 +- 修改 SSH 配置前先保留一个已登录会话。 +- 修改配置后执行 `sshd -t` 检查语法。 + +## 高危提醒 + +- 不要在远程会话里直接停止 SSH 服务后退出。 +- 修改防火墙规则前确认不会阻断当前管理通道。 diff --git a/docs/cases/TLS-CHAIN-INCOMPLETE.md b/docs/cases/TLS-CHAIN-INCOMPLETE.md new file mode 100644 index 0000000..a012af5 --- /dev/null +++ b/docs/cases/TLS-CHAIN-INCOMPLETE.md @@ -0,0 +1,47 @@ +# TLS 证书链不完整排查 + +## 现象 + +- 浏览器或客户端提示证书不受信任。 +- `curl` 提示 `unable to get local issuer certificate`。 +- 部分客户端正常，部分客户端失败。 +- 移动端或老系统访问 HTTPS 失败。 + +## 快速判断 + +```bash +echo | openssl s_client -servername example.com -connect example.com:443 -showcerts 2>/dev/null +``` + +## 排查命令 + +```bash +# 查看线上证书链 +echo | openssl s_client -servername example.com -connect example.com:443 -showcerts 2>/dev/null | openssl x509 -noout -subject -issuer + +# 查看本地证书 +openssl x509 -in /path/to/cert.pem -noout -subject -issuer -dates + +# 查看 Nginx 证书配置 +nginx -T | grep -E "ssl_certificate|ssl_certificate_key" +``` + +## 常见原因 + +- 服务端只配置了站点证书，没有配置中间证书。 +- 证书文件顺序错误。 +- 使用了错误的 CA bundle。 +- 负载均衡、Ingress、网关仍在使用旧证书。 +- 客户端信任库过旧。 + +## 处理建议 + +- 使用包含站点证书和中间证书的 fullchain 文件。 +- Nginx 通常应将 `ssl_certificate` 指向 fullchain。 +- 更新证书后 reload 服务，并确认线上实际证书链。 +- 多层代理环境逐层确认 TLS 终止位置。 + +## 高危提醒 + +- 不要覆盖旧证书文件后直接重启，先备份。 +- 不要把私钥提交到 Git 仓库或粘贴到 Issue。 diff --git a/docs/containers/DOCKER-KUBERNETES-CHEATSHEET.md b/docs/containers/DOCKER-KUBERNETES-CHEATSHEET.md new file mode 100644 index 0000000..81daa91 --- /dev/null +++ b/docs/containers/DOCKER-KUBERNETES-CHEATSHEET.md @@ -0,0 +1,119 @@ +# Docker 与 Kubernetes 运维速查 + +这个页面覆盖容器和 Kubernetes 的高频查看、排障和发布命令。生产环境执行变更命令前，请先确认命名空间、上下文和目标资源。 + +## Docker 常用命令 + +```bash +# 查看容器 +docker ps +docker ps -a + +# 查看镜像 +docker images + +# 查看日志 +docker logs +docker logs -f --tail 100 + +# 进入容器 +docker exec -it sh + +# 查看容器资源 +docker stats + +# 查看容器详情 +docker inspect +``` + +## Docker 排障 + +```bash +# 查看容器退出原因 +docker ps -a +docker logs + +# 查看端口映射 +docker port + +# 查看容器内进程 +docker top +``` + +高危提醒: + +- `docker system prune -a` 会删除未使用镜像、容器和缓存，执行前要确认。 +- 不建议在生产环境随意删除 volume。 + +## Kubernetes 上下文 + +```bash +# 查看当前上下文 +kubectl config current-context + +# 查看所有上下文 +kubectl config get-contexts + +# 切换上下文 +kubectl config use-context + +# 查看命名空间 +kubectl get ns +``` + +## Kubernetes 查看资源 + +```bash +# 查看 Pod +kubectl get pods -A +kubectl get pods -n + +# 查看服务 +kubectl get svc -n + +# 查看部署 +kubectl get deploy -n + +# 查看事件 +kubectl get events -n --sort-by=.lastTimestamp +``` + +## Kubernetes 日志与排障 + +```bash +# 查看日志 +kubectl logs -n +kubectl logs -f -n + +# 多容器 Pod 指定容器 +kubectl logs -c -n + +# 查看资源详情 +kubectl describe pod -n + +# 进入容器 +kubectl exec -it -n -- sh +``` + +## 发布与回滚 + +```bash +# 查看发布状态 +kubectl rollout status deploy/ -n + +# 查看历史版本 +kubectl rollout history deploy/ -n + +# 回滚上一个版本 +kubectl rollout undo deploy/ -n +``` + +## 常见问题 + +| 现象 | 优先排查 | +| --- | --- | +| `CrashLoopBackOff` | `kubectl logs`、`kubectl describe pod` | +| `ImagePullBackOff` | 镜像地址、镜像仓库权限、网络 | +| `Pending` | 节点资源、调度约束、PVC | +| `Service` 不通 | Endpoints、Pod 标签、端口映射 | +| 配置不生效 | ConfigMap/Secret 挂载方式、Pod 是否重启 | diff --git a/docs/domestic-linux/ARCHITECTURE-CHECKLIST.md b/docs/domestic-linux/ARCHITECTURE-CHECKLIST.md new file mode 100644 index 0000000..f9f565a --- /dev/null +++ b/docs/domestic-linux/ARCHITECTURE-CHECKLIST.md @@ -0,0 +1,57 @@ +# 信创环境架构与兼容性检查 + +国产化环境中，同一个命令或软件包可能因为 CPU 架构、系统版本、厂商补丁而表现不同。排查问题前，先收集基础信息。 + +## 基础信息采集 + +```bash +cat /etc/os-release +uname -a +uname -m +lscpu +``` + +## 包管理与软件源 + +```bash +# APT 系 +apt policy 2>/dev/null +apt list --installed 2>/dev/null | head + +# RPM 系 +yum repolist 2>/dev/null +rpm -qa | head +``` + +## 常见架构 + +| 架构 | 常见场景 | 注意事项 | +| --- | --- | --- | +| `x86_64` | 通用服务器和桌面 | 软件兼容性最好 | +| `aarch64` | ARM 服务器、终端 | 注意软件包架构和镜像架构 | +| `loongarch64` | 龙芯环境 | 需要确认软件生态和专用源 | +| `mips64el` | 部分国产平台 | 通用二进制兼容性有限 | + +## 容器镜像检查 + +```bash +# 查看本机架构 +uname -m + +# 查看镜像信息 +docker image inspect +``` + +建议: + +- ARM 环境优先使用多架构镜像。 +- 不确定镜像架构时，先在测试环境启动。 +- CI 构建时明确目标架构。 + +## 排查清单 + +- 系统版本是否与文档一致。 +- CPU 架构是否与软件包一致。 +- 软件源是否匹配系统版本。 +- 内核版本是否满足驱动或软件要求。 +- 安全中心、防火墙、访问控制是否限制服务。 diff --git a/docs/domestic-linux/KYLIN-UOS-COMMANDS.md b/docs/domestic-linux/KYLIN-UOS-COMMANDS.md new file mode 100644 index 0000000..639182a --- /dev/null +++ b/docs/domestic-linux/KYLIN-UOS-COMMANDS.md @@ -0,0 +1,296 @@ +# 银河麒麟与统信 UOS 常用命令 + +银河麒麟和统信 UOS 常见于政企办公、国产化替代和信创环境。实际命令会因版本、CPU 架构和软件源策略不同而变化，执行前建议先确认系统版本。 + +## 系统版本识别 + +```bash +# 通用方式 +cat /etc/os-release + +# 内核和架构 +uname -a +uname -m + +# systemd 版本 +systemctl --version +``` + +### 银河麒麟 + +```bash +# 查看银河麒麟版本 +cat /etc/kylin-release +cat /etc/.kyinfo + +# 查看详细系统信息 +nkvers + +# 查看定制内核 +uname -r + +# 查看安全中心和审计服务 +systemctl status kylin-security-center +systemctl status auditd +``` + +### 统信 UOS + +```bash +# 查看统信 UOS 版本 +cat /etc/uos-release +cat /etc/os-version + +# 查看详细版本信息 +uosvers + +# 查看内核和激活状态 +uname -r +uos-activation status + +# 查看安全中心状态 +systemctl status deepin-defender +``` + +## 软件包管理 + +### Debian/Ubuntu 系兼容场景 + +```bash +# 更新软件源 +sudo apt update + +# 安装软件 +sudo apt install + +# 查询软件 +apt search + +# 查看已安装包 +dpkg -l | grep +``` + +### RPM/YUM/DNF 兼容场景 + +```bash +# 查询仓库 +yum repolist + +# 安装软件 +sudo yum install + +# 查询软件包 +rpm -qa | grep + +# 查看文件属于哪个包 +rpm -qf /path/to/file +``` + +### 银河麒麟专用场景 + +```bash +# 安装银河麒麟安全和系统管理工具 +sudo apt install kylin-security-tool +sudo apt install kylin-system-manager + +# 查看软件商店命令行工具 +kylin-software-center --help + +# 查看已安装的麒麟相关包 +dpkg -l | grep kylin + +# 如需兼容 UOS 应用，先确认厂商支持策略 +apt search uos-compat +``` + +### 统信 UOS 专用场景 + +```bash +# 查看深度商店命令行工具 +deepin-store-cli --help + +# 安装统信安全中心和系统工具 +sudo apt install uos-security-center +sudo apt install uos-system-tools + +# 查看已安装的统信和 deepin 相关包 +dpkg -l | grep uos +dpkg -l | grep deepin + +# 查看统信软件源 +cat /etc/apt/sources.list.d/uos.list + +# 搜索内核更新包 +apt search linux-image-uos +``` + +## 服务管理 + +```bash +# 查看服务 +systemctl status + +# 启动服务 +sudo systemctl start + +# 设置开机启动 +sudo systemctl enable + +# 查看失败服务 +systemctl --failed +``` + +### 厂商服务 + +```bash +# 银河麒麟更新、备份和远程协助 +systemctl status kylin-update +systemctl status kylin-backup +systemctl status kylin-remote-assistance +systemctl status kylin-auth + +# 统信 UOS 更新、备份和远程协助 +systemctl status uos-update +systemctl status uos-backup +systemctl status uos-remote-assist +systemctl status uos-auth +``` + +## 安全中心与访问控制 + +### 银河麒麟 + +```bash +# 查看安全中心策略 +kylin-security-cli status + +# 启用或禁用安全中心，生产环境先确认影响范围 +kylin-security-cli enable +kylin-security-cli disable + +# AppArmor 和审计 +aa-status +aa-enabled +ausearch -m avc -ts today + +# 安全日志 +tail -f /var/log/kylin-security.log +``` + +### 统信 UOS + +```bash +# 安全中心 +deepin-defender status +deepin-defender start + +# 病毒扫描 +deepin-defender scan /path/to/scan + +# 防火墙 +uos-firewall status +uos-firewall enable +uos-firewall allow 80/tcp +uos-firewall allow 443/tcp + +# 审计与白名单 +cat /var/log/uos/security.log +uos-app-whitelist list +uos-app-whitelist add /path/to/app +uos-security-level +``` + +## 网络排查 + +```bash +# 查看 IP +ip addr + +# 查看路由 +ip route + +# 查看监听端口 +ss -tulnp + +# 测试连通 +ping +``` + +## 桌面与图形环境 + +```bash +# 查看当前桌面会话 +echo $XDG_CURRENT_DESKTOP + +# 查看显示服务 +loginctl show-session "$XDG_SESSION_ID" -p Type +``` + +## 备份、诊断与高级功能 + +### 银河麒麟 + +```bash +# 检查更新 +kylin-update-check + +# 备份与恢复 +kylin-backup create --full +kylin-backup restore /path/to/backup + +# 安全级别和完整性 +kylin-security-level +kylin-security-level set 2 +kylin-integrity-check + +# 诊断报告 +kylin-diagnose +kylin-diagnose --report /path/to/report.html + +# 查看定制参数 +sysctl -a | grep kylin +``` + +### 统信 UOS + +```bash +# 更新 +uos-update check +uos-update upgrade + +# 备份与恢复 +uos-backup create --name "system-backup" +uos-backup list +uos-backup restore + +# 完整性和诊断 +uos-verify +uos-diagnose +uos-diagnose --report /path/to/report.pdf + +# 定制内核和应用容器 +sysctl -a | grep uos +lsmod | grep uos +uos-app-container list +uos-app-container run + +# 文件保护 +uos-file-protection status +uos-file-protection enable +uos-file-protection add /path/to/protect +``` + +## 信创环境建议 + +- 记录系统版本、CPU 架构、软件源地址和补丁策略。 +- 不同厂商镜像的包名可能不一致，先搜索再安装。 +- 内网环境建议维护离线软件包仓库。 +- 修改安全中心、防火墙、访问控制策略前先保存当前配置。 +- 厂商命令随版本和授权组件变化较大，找不到命令时先用 `dpkg -l`、`rpm -qa` 或软件商店确认组件是否安装。 +- 更新、备份、恢复和安全级别调整都应先在测试机验证。 + +## 延伸阅读 + +- [国产 Linux 离线安装与软件源维护](OFFLINE-PACKAGE-GUIDE.md) +- [信创环境架构与兼容性检查](ARCHITECTURE-CHECKLIST.md) +- [国产 Linux 版本差异与排查要点](VERSION-DIFFERENCES.md) diff --git a/docs/domestic-linux/OFFLINE-PACKAGE-GUIDE.md b/docs/domestic-linux/OFFLINE-PACKAGE-GUIDE.md new file mode 100644 index 0000000..ae394a7 --- /dev/null +++ b/docs/domestic-linux/OFFLINE-PACKAGE-GUIDE.md @@ -0,0 +1,94 @@ +# 国产 Linux 离线安装与软件源维护 + +信创和内网环境经常无法直接访问公网软件源。银河麒麟、统信 UOS 等系统在离线安装时，建议优先建立内部软件源，而不是长期手工拷贝单个安装包。 + +## 先确认系统信息 + +```bash +cat /etc/os-release +uname -m +dpkg --print-architecture 2>/dev/null || rpm --eval '%{_arch}' 2>/dev/null +``` + +需要记录: + +- 发行版和版本号 +- CPU 架构: `x86_64`、`aarch64`、`loongarch64` 等 +- 包管理器: `apt`、`yum`、`dnf` +- 是否有厂商专用源或内网源 + +## Debian/Ubuntu/UOS 兼容环境 + +### 下载软件包及依赖 + +联网机器: + +```bash +mkdir -p packages +cd packages +apt download +``` + +如果需要递归下载依赖，建议使用受控工具或在干净环境中模拟安装，避免漏包。 + +### 离线安装 + +目标机器: + +```bash +sudo dpkg -i *.deb +sudo apt -f install +``` + +如果完全离线，`apt -f install` 仍可能失败，需要把缺失依赖一起准备好。 + +## RPM/YUM/DNF 兼容环境 + +### 下载软件包及依赖 + +联网机器: + +```bash +mkdir -p packages +yum install --downloadonly --downloaddir=packages +``` + +或: + +```bash +dnf download --resolve --destdir packages +``` + +### 离线安装 + +目标机器: + +```bash +sudo rpm -Uvh *.rpm +``` + +如果依赖复杂，建议建立本地 yum 仓库。 + +## 本地软件源建议 + +适合团队或多台服务器: + +- 统一维护内网仓库。 +- 按系统版本和架构分目录。 +- 保留软件包来源和更新时间。 +- 上线前在测试机验证依赖完整性。 + +## 常见问题 + +| 问题 | 排查 | +| --- | --- | +| 架构不匹配 | `uname -m`、包名中的架构后缀 | +| 依赖缺失 | 查看 `dpkg -i` 或 `rpm -Uvh` 报错 | +| 软件源不可用 | 检查 `/etc/apt/sources.list` 或 `/etc/yum.repos.d/` | +| 证书或签名失败 | 检查仓库 GPG key 和系统时间 | + +## 安全建议 + +- 不从不可信来源下载系统包。 +- 内网仓库要有访问控制和变更记录。 +- 生产系统安装前先在同版本测试环境验证。 diff --git a/docs/domestic-linux/VERSION-DIFFERENCES.md b/docs/domestic-linux/VERSION-DIFFERENCES.md new file mode 100644 index 0000000..606e85e --- /dev/null +++ b/docs/domestic-linux/VERSION-DIFFERENCES.md @@ -0,0 +1,115 @@ +# 国产 Linux 版本差异与排查要点 + +国产 Linux 环境常见差异来自发行版版本、CPU 架构、软件源、桌面/服务器形态和厂商安全组件。排查前先收集环境信息。 + +## 基础信息采集 + +```bash +cat /etc/os-release +uname -a +uname -m +lscpu +systemctl --version +``` + +## 银河麒麟常见关注点 + +```bash +# 系统版本 +cat /etc/os-release + +# 包管理器判断 +command -v apt +command -v yum +command -v dnf + +# 服务管理 +systemctl status +``` + +关注点: + +- 不同镜像可能使用不同包管理体系。 +- 服务器版和桌面版预装组件不同。 +- ARM、龙芯等架构的软件包可用性不同。 +- 安全中心或访问控制策略可能影响服务访问。 + +## 统信 UOS 常见关注点 + +```bash +# 系统版本 +cat /etc/os-release + +# APT 源 +cat /etc/apt/sources.list +ls /etc/apt/sources.list.d/ + +# 已安装包 +dpkg -l | head +``` + +关注点: + +- 桌面版和服务器版包集合不同。 +- 内网环境常使用定制软件源。 +- 图形界面组件和服务端组件排查方式不同。 +- 某些安全策略可能通过图形安全中心配置。 + +## 架构差异 + +| 架构 | 排查重点 | +| --- | --- | +| `x86_64` | 通用软件兼容性较好 | +| `aarch64` | 注意 ARM 包、容器镜像架构 | +| `loongarch64` | 注意专用软件源和二进制兼容 | +| `mips64el` | 注意可用包范围和厂商适配 | + +## 软件源差异 + +排查命令: + +```bash +# APT +apt policy +sudo apt update + +# YUM/DNF +yum repolist -v +dnf repolist -v +``` + +常见问题: + +- 软件源版本与系统版本不匹配。 +- 源地址内网不可达。 +- GPG key 或证书异常。 +- 架构目录缺失。 + +## 安全组件差异 + +排查顺序: + +1. Linux 文件权限。 +2. 防火墙。 +3. SELinux/AppArmor。 +4. 厂商安全中心或访问控制策略。 +5. 等保/基线加固脚本带来的限制。 + +## 建议记录模板 + +```text +系统名称: +系统版本: +CPU 架构: +包管理器: +软件源地址: +安全组件: +部署环境: 物理机/虚拟机/云主机/容器 +问题现象: +``` + +延伸阅读: + +- [银河麒麟与统信 UOS 常用命令](KYLIN-UOS-COMMANDS.md) +- [国产 Linux 离线安装与软件源维护](OFFLINE-PACKAGE-GUIDE.md) +- [信创环境架构与兼容性检查](ARCHITECTURE-CHECKLIST.md) diff --git a/docs/examples/linux-health-check.sample.json b/docs/examples/linux-health-check.sample.json new file mode 100644 index 0000000..37befc6 --- /dev/null +++ b/docs/examples/linux-health-check.sample.json @@ -0,0 +1,67 @@ +{ + "metadata": { + "os": "Linux", + "hostname": "example-linux-host", + "timestamp": "2026-05-07T08:00:00Z", + "module": "all", + "format": "json", + "script": "linux-health-check.sh" + }, + "modules": { + "system": { + "status": "ok", + "commands": [ + { + "name": "uname", + "command": "uname -a", + "exit_code": 0, + "output": "Linux example-linux-host 6.1.0 x86_64 GNU/Linux" + } + ], + "warnings": [], + "errors": [] + }, + "disk": { + "status": "ok", + "commands": [ + { + "name": "disk", + "command": "df -h", + "exit_code": 0, + "output": "Filesystem Size Used Avail Use% Mounted on\n/dev/sda1 100G 40G 60G 40% /" + } + ], + "warnings": [], + "errors": [] + }, + "network": { + "status": "warning", + "commands": [], + "warnings": [ + { + "name": "ss", + "message": "Command not available: ss" + } + ], + "errors": [] + }, + "service": { + "status": "skipped", + "commands": [], + "warnings": [], + "errors": [] + }, + "process": { + "status": "skipped", + "commands": [], + "warnings": [], + "errors": [] + } + }, + "summary": { + "status": "warning", + "warnings_count": 1, + "errors_count": 0 + }, + "errors": [] +} diff --git a/docs/examples/windows-health-check.sample.json b/docs/examples/windows-health-check.sample.json new file mode 100644 index 0000000..9e2b8fb --- /dev/null +++ b/docs/examples/windows-health-check.sample.json @@ -0,0 +1,55 @@ +{ + "metadata": { + "os": "Windows", + "hostname": "EXAMPLE-WIN-HOST", + "timestamp": "2026-05-07T08:00:00Z", + "module": "all", + "format": "json", + "script": "windows-health-check.ps1" + }, + "modules": { + "system": { + "status": "ok", + "commands": [ + { + "name": "computer_info", + "command": "Get-ComputerInfo | Select-Object CsName, WindowsProductName, WindowsVersion, OsArchitecture", + "exit_code": 0, + "output": "CsName WindowsProductName WindowsVersion OsArchitecture\n------ ------------------ -------------- --------------\nEXAMPLE-WIN-HOST Windows Server 2022 2009 64-bit" + } + ], + "warnings": [], + "errors": [] + }, + "disk": { + "status": "ok", + "commands": [], + "warnings": [], + "errors": [] + }, + "network": { + "status": "ok", + "commands": [], + "warnings": [], + "errors": [] + }, + "service": { + "status": "skipped", + "commands": [], + "warnings": [], + "errors": [] + }, + "process": { + "status": "skipped", + "commands": [], + "warnings": [], + "errors": [] + } + }, + "summary": { + "status": "ok", + "warnings_count": 0, + "errors_count": 0 + }, + "errors": [] +} diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..fd2871a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,76 @@ +# Windows PowerShell 与 Linux 常用命令手册 + +一份中文命令速查与运维排障文档，覆盖 Windows PowerShell、Linux、银河麒麟、统信 UOS 和跨平台脚本场景。 + +## 快速入口 + +| 需求 | 文档 | +| --- | --- | +| 常见问题 | [FAQ](FAQ.md) | +| 按命令查找 | [命令索引](COMMAND-INDEX.md) | +| 覆盖面评估 | [命令覆盖矩阵](COMMAND-COVERAGE-MATRIX.md) | +| 迁移进度 | [主手册专题化迁移进度](MANUAL-MIGRATION.md) | +| 下一阶段 | [下一阶段优化计划](NEXT-STAGE-PLAN.md) | +| 快速查命令 | [命令速查表](COMMAND-CHEATSHEET.md) | +| 专题化手册 | [完整手册专题化入口](manual/README.md) | +| Linux 包管理 | [Linux 包管理](manual/linux/PACKAGE-MANAGEMENT.md) | +| Linux 用户权限 | [Linux 用户、组与权限](manual/linux/USERS-PERMISSIONS.md) | +| Shell 脚本 | [Shell 脚本基础与高级技巧](manual/linux/SHELL-SCRIPTING.md) | +| 磁盘与 LVM | [Linux 磁盘、挂载与 LVM](manual/linux/DISK-LVM.md) | +| 性能调优 | [Linux 性能调优](manual/linux/PERFORMANCE-TUNING.md) | +| 系统监控/日志 | [Linux 系统监控与日志](manual/linux/MONITORING-LOGS.md) | +| 防火墙/SELinux | [防火墙与 SELinux](manual/security/FIREWALL-SELINUX.md) | +| 日志与审计 | [日志轮转、审计与系统日志](manual/security/LOGGING-AUDIT.md) | +| sudoers/AppArmor | [sudoers 与 AppArmor](manual/security/SUDOERS-APPARMOR.md) | +| Windows 管理 | [Windows 管理命令](manual/windows/ADMIN-COMMANDS.md) | +| Kubernetes 进阶 | [Kubernetes 进阶排查](manual/kubernetes/ADVANCED-TROUBLESHOOTING.md) | +| Docker/Kubernetes 生产命令 | [Docker 与 Kubernetes 生产级命令](manual/kubernetes/DOCKER-K8S-PRODUCTION.md) | +| 数据库/中间件 | [数据库与中间件命令](manual/middleware/DATABASE-MIDDLEWARE.md) | +| PostgreSQL/MongoDB/Elasticsearch | [PostgreSQL、MongoDB 与 Elasticsearch](manual/middleware/POSTGRES-MONGO-ELASTIC.md) | +| 云服务器/负载均衡 | [云服务器与负载均衡排查](manual/cloud/CLOUD-LB-TROUBLESHOOTING.md) | +| 监控告警 | [集中日志与监控告警](manual/observability/LOGGING-MONITORING.md) | +| PromQL/LogQL | [PromQL、LogQL 与告警规则](manual/observability/PROMQL-LOGQL-ALERTS.md) | +| 开发工具 | [Git、SSH、curl 与 jq](manual/devtools/GIT-SSH-CURL-JQ.md) | +| 巡检脚本 | [巡检脚本工具化](manual/automation/HEALTH-CHECK-SCRIPTS.md) | +| 跨平台脚本 | [Python 与 Node.js 跨平台脚本](manual/cross-platform/PYTHON-NODE-SCRIPTS.md) | +| 高可用 | [Keepalived 高可用](manual/ha/KEEPALIVED.md) | +| Windows/Linux 迁移 | [PowerShell 与 Bash 命令对照](POWERSHELL-BASH-COMPARISON.md) | +| PowerShell 实战 | [PowerShell 实用场景](powershell/POWERSHELL-PRACTICAL.md) | +| Bash 文本处理 | [Bash 文本处理速查](linux/BASH-TEXT-PROCESSING.md) | +| Linux 线上排障 | [Linux 故障应急排查清单](troubleshooting/LINUX-INCIDENT-CHECKLIST.md) | +| 常见报错 | [常见报错排查](troubleshooting/COMMON-ERRORS.md) | +| 真实故障案例 | [真实故障案例库](cases/README.md) | +| 监控告警故障 | [Prometheus Target Down](cases/PROMETHEUS-TARGET-DOWN.md) / [Grafana 无数据](cases/GRAFANA-NO-DATA.md) | +| Kubernetes DNS | [Kubernetes DNS 异常排查](cases/K8S-DNS-FAILED.md) | +| Docker/Kubernetes | [Docker 与 Kubernetes 运维速查](containers/DOCKER-KUBERNETES-CHEATSHEET.md) | +| 国产 Linux 运维 | [银河麒麟与统信 UOS 常用命令](domestic-linux/KYLIN-UOS-COMMANDS.md) | +| 离线安装/软件源 | [国产 Linux 离线安装与软件源维护](domestic-linux/OFFLINE-PACKAGE-GUIDE.md) | +| 国产系统差异 | [国产 Linux 版本差异与排查要点](domestic-linux/VERSION-DIFFERENCES.md) | +| 命令安全 | [命令风险等级说明](security/RISK-LEVELS.md) | +| GitHub 项目优化 | [GitHub 热度优化清单](GITHUB-GROWTH-CHECKLIST.md) | +| 项目审查 | [项目整体审查报告](PROJECT-AUDIT.md) | +| 新手任务 | [Good First Issues 清单](GOOD-FIRST-ISSUES.md) | +| 项目维护 | [维护者指南](MAINTAINER-GUIDE.md) | +| 发布检查 | [Release 检查清单](RELEASE-CHECKLIST.md) | +| Release 草案 | [v2.16.0 Release 草案](RELEASE-2.16-DRAFT.md) | + +## 学习路线 + +| 路线 | 建议顺序 | +| --- | --- | +| 新手入门 | [命令速查表](COMMAND-CHEATSHEET.md) -> [PowerShell 基础](manual/powershell/BASIC.md) -> [Linux 基础](manual/linux/BASIC.md) | +| 运维值班 | [Linux 应急排查](troubleshooting/LINUX-INCIDENT-CHECKLIST.md) -> [真实故障案例](cases/README.md) -> [命令风险等级](security/RISK-LEVELS.md) | +| 国产 Linux | [麒麟与 UOS](domestic-linux/KYLIN-UOS-COMMANDS.md) -> [离线安装](domestic-linux/OFFLINE-PACKAGE-GUIDE.md) -> [版本差异](domestic-linux/VERSION-DIFFERENCES.md) | +| 容器/Kubernetes | [Docker/Kubernetes 生产命令](manual/kubernetes/DOCKER-K8S-PRODUCTION.md) -> [Kubernetes 进阶排查](manual/kubernetes/ADVANCED-TROUBLESHOOTING.md) -> [K8s 故障案例](cases/README.md) | +| 脚本自动化 | [Shell 脚本](manual/linux/SHELL-SCRIPTING.md) -> [跨平台脚本](manual/cross-platform/PYTHON-NODE-SCRIPTS.md) -> [巡检脚本工具化](manual/automation/HEALTH-CHECK-SCRIPTS.md) | + +## 项目定位 + +- 面向新手: 提供常用命令和简明说明。 +- 面向开发者: 提供 PowerShell 与 Bash 迁移对照。 +- 面向运维: 提供系统、进程、网络、日志、服务排查命令。 +- 面向信创环境: 提供银河麒麟与统信 UOS 常用操作入口。 + +## 安全提醒 + +删除、格式化、权限递归修改、服务重启等命令可能影响系统稳定性或数据安全。执行前请确认目标路径、备份状态和当前环境。 diff --git a/docs/linux/BASH-TEXT-PROCESSING.md b/docs/linux/BASH-TEXT-PROCESSING.md new file mode 100644 index 0000000..7d8b796 --- /dev/null +++ b/docs/linux/BASH-TEXT-PROCESSING.md @@ -0,0 +1,67 @@ +# Bash 文本处理速查 + +Linux 排障和日志分析经常依赖文本处理。`grep`、`awk`、`sed` 是最常见的三类工具。 + +## grep 搜索 + +```bash +# 搜索关键字 +grep "error" app.log + +# 忽略大小写 +grep -i "error" app.log + +# 显示行号 +grep -n "error" app.log + +# 递归搜索 +grep -R "error" /var/log + +# 使用扩展正则 +grep -E "error|failed|timeout" app.log +``` + +## awk 列处理 + +```bash +# 打印第一列 +awk '{print $1}' access.log + +# 按状态码统计 +awk '{print $9}' access.log | sort | uniq -c | sort -nr + +# 筛选大于 1000 的值 +awk '$10 > 1000 {print $0}' access.log +``` + +## sed 替换 + +```bash +# 预览替换结果 +sed 's/old/new/g' file.txt + +# 原地替换 +sed -i 's/old/new/g' file.txt + +# 删除空行 +sed '/^$/d' file.txt +``` + +## 常见组合 + +```bash +# 查看错误最多的 IP +grep "500" access.log | awk '{print $1}' | sort | uniq -c | sort -nr | head + +# 查看最近 100 行中的错误 +tail -n 100 app.log | grep -i "error" + +# 从日志中提取时间和错误信息 +grep -i "error" app.log | awk '{print $1, $2, $0}' +``` + +## 使用建议 + +- 生产日志很大时，优先用 `tail`、`head`、时间范围或更精确的关键词缩小范围。 +- 批量替换前先不加 `-i` 预览结果。 +- 命令较复杂时保存为脚本，方便复用和审查。 diff --git a/docs/manual/README.md b/docs/manual/README.md new file mode 100644 index 0000000..1e4b436 --- /dev/null +++ b/docs/manual/README.md @@ -0,0 +1,46 @@ +# 完整手册专题化入口 + +主手册仍保留在仓库根目录: [Windows-PowerShell-Linux-Command-Manual.md](https://github.com/shiwenxin123/PowerShell-Linux-/blob/main/Windows-PowerShell-Linux-Command-Manual.md)。 + +这个目录用于把 3000 多行完整手册逐步拆成更容易阅读和维护的专题页。当前先提供结构化入口和高频内容摘要，后续可以把主手册原文逐章迁移进来。 + +## 专题列表 + +| 专题 | 文档 | +| --- | --- | +| PowerShell 基础 | [PowerShell 基础命令](powershell/BASIC.md) | +| PowerShell 系统管理 | [PowerShell 系统管理](powershell/SYSTEM-ADMIN.md) | +| PowerShell 高级技巧 | [PowerShell 高级技巧](powershell/ADVANCED-SCRIPTING.md) | +| Linux 基础 | [Linux 基础命令](linux/BASIC.md) | +| Linux 包管理 | [Linux 包管理](linux/PACKAGE-MANAGEMENT.md) | +| Linux 用户、组与权限 | [Linux 用户、组与权限](linux/USERS-PERMISSIONS.md) | +| Shell 脚本 | [Shell 脚本基础与高级技巧](linux/SHELL-SCRIPTING.md) | +| Linux 网络排查 | [Linux 网络排查](linux/NETWORK.md) | +| Linux 存储与日志 | [Linux 存储与日志](linux/STORAGE-LOGS.md) | +| Linux 系统监控与日志 | [Linux 系统监控与日志](linux/MONITORING-LOGS.md) | +| Linux 磁盘与 LVM | [Linux 磁盘、挂载与 LVM](linux/DISK-LVM.md) | +| Linux 性能调优 | [Linux 性能调优](linux/PERFORMANCE-TUNING.md) | +| 安全加固 | [系统安全加固](security/HARDENING.md) | +| 防火墙与 SELinux | [防火墙与 SELinux](security/FIREWALL-SELINUX.md) | +| 日志轮转与审计 | [日志轮转、审计与系统日志](security/LOGGING-AUDIT.md) | +| sudoers 与 AppArmor | [sudoers 与 AppArmor](security/SUDOERS-APPARMOR.md) | +| Windows 管理 | [Windows 管理命令](windows/ADMIN-COMMANDS.md) | +| Kubernetes 进阶排查 | [Kubernetes 进阶排查](kubernetes/ADVANCED-TROUBLESHOOTING.md) | +| Docker 与 Kubernetes 生产级命令 | [Docker 与 Kubernetes 生产级命令](kubernetes/DOCKER-K8S-PRODUCTION.md) | +| 数据库与中间件 | [数据库与中间件命令](middleware/DATABASE-MIDDLEWARE.md) | +| PostgreSQL/MongoDB/Elasticsearch | [PostgreSQL、MongoDB 与 Elasticsearch](middleware/POSTGRES-MONGO-ELASTIC.md) | +| 云服务器与负载均衡 | [云服务器与负载均衡排查](cloud/CLOUD-LB-TROUBLESHOOTING.md) | +| 集中日志与监控告警 | [集中日志与监控告警](observability/LOGGING-MONITORING.md) | +| PromQL/LogQL/告警规则 | [PromQL、LogQL 与告警规则](observability/PROMQL-LOGQL-ALERTS.md) | +| 开发与排障工具 | [开发与排障工具](devtools/README.md) | +| 巡检脚本工具化 | [巡检脚本工具化](automation/HEALTH-CHECK-SCRIPTS.md) | +| Python 与 Node.js 跨平台脚本 | [Python 与 Node.js 跨平台脚本](cross-platform/PYTHON-NODE-SCRIPTS.md) | +| Keepalived 高可用 | [Keepalived 高可用](ha/KEEPALIVED.md) | +| 跨平台工具 | [跨平台脚本与工具](cross-platform/TOOLS.md) | + +## 拆分原则 + +- README 和索引页只放入口，不堆长命令。 +- 单个专题尽量控制在一个明确场景内。 +- 高危命令必须链接到 [命令风险等级说明](../security/RISK-LEVELS.md)。 +- 与故障相关的内容优先沉淀到 [真实故障案例库](../cases/README.md)。 diff --git a/docs/manual/automation/HEALTH-CHECK-SCRIPTS.md b/docs/manual/automation/HEALTH-CHECK-SCRIPTS.md new file mode 100644 index 0000000..cdf941f --- /dev/null +++ b/docs/manual/automation/HEALTH-CHECK-SCRIPTS.md @@ -0,0 +1,100 @@ +# 巡检脚本工具化 + +Linux 和 Windows 巡检脚本支持文本、Markdown 和 JSON 输出。JSON 输出使用统一结构，便于 CI、自动化平台或巡检系统消费。 + +## 支持格式 + +| 格式 | 用途 | +| --- | --- | +| `text` | 默认终端输出 | +| `markdown` | 生成可粘贴到工单或文档的报告 | +| `json` | 自动化消费和后续结构化处理 | + +## 支持模块 + +| 模块 | 说明 | +| --- | --- | +| `all` | 默认，执行全部检查 | +| `system` | 系统版本、运行时间、内存等 | +| `disk` | 磁盘空间、inode 或驱动器信息 | +| `network` | 监听端口和网络路由 | +| `service` | 异常服务或未运行服务 | +| `process` | CPU 和内存占用较高的进程 | + +## Linux 示例 + +```bash +# 默认文本输出 +bash scripts/linux-health-check.sh + +# 只检查磁盘 +bash scripts/linux-health-check.sh --module disk + +# Markdown 报告 +bash scripts/linux-health-check.sh --format markdown --output reports/linux-health-check.md + +# JSON 报告 +bash scripts/linux-health-check.sh --format json --output reports/linux-health-check.json +``` + +## Windows 示例 + +```powershell +# 默认文本输出 +.\scripts\windows-health-check.ps1 + +# 只检查网络 +.\scripts\windows-health-check.ps1 -Module network + +# Markdown 报告 +.\scripts\windows-health-check.ps1 -Format markdown -OutputFile reports\windows-health-check.md + +# JSON 报告 +.\scripts\windows-health-check.ps1 -Format json -OutputFile reports\windows-health-check.json +``` + +## JSON 结构 + +完整字段契约见 [Health Check Report JSON Schema](../../schema/health-check-report.schema.json)。 + +```json +{ + "metadata": { + "os": "Linux", + "hostname": "example-host", + "timestamp": "2026-05-07T08:00:00Z", + "module": "all", + "format": "json", + "script": "linux-health-check.sh" + }, + "modules": { + "system": { + "status": "ok", + "commands": [], + "warnings": [], + "errors": [] + } + }, + "summary": { + "status": "ok", + "warnings_count": 0, + "errors_count": 0 + }, + "errors": [] +} +``` + +## 退出码 + +| 退出码 | 含义 | +| --- | --- | +| `0` | 巡检正常完成且无告警 | +| `1` | 巡检完成但存在告警或部分模块异常 | +| `2` | 参数错误 | +| `3` | 脚本内部异常或关键输出写入失败 | + +## 示例报告 + +- [Linux JSON 示例](../../examples/linux-health-check.sample.json) +- [Windows JSON 示例](../../examples/windows-health-check.sample.json) +- [JSON Schema](../../schema/health-check-report.schema.json) diff --git a/docs/manual/cloud/CLOUD-LB-TROUBLESHOOTING.md b/docs/manual/cloud/CLOUD-LB-TROUBLESHOOTING.md new file mode 100644 index 0000000..556b26d --- /dev/null +++ b/docs/manual/cloud/CLOUD-LB-TROUBLESHOOTING.md @@ -0,0 +1,117 @@ +# 云服务器与负载均衡排查 + +云上故障排查要同时看系统内部和云平台侧配置。很多“服务不通”并不是服务本身问题，而是安全组、负载均衡、NAT、路由或健康检查异常。 + +## 云服务器基础检查 + +```bash +# 系统状态 +uptime +free -h +df -h + +# 网络地址和路由 +ip addr +ip route + +# 监听端口 +ss -tulnp +``` + +PowerShell: + +```powershell +Get-ComputerInfo +Get-NetIPConfiguration +Get-NetTCPConnection -State Listen +``` + +## 安全组与防火墙 + +排查顺序: + +1. 应用是否监听正确端口。 +2. 本机防火墙是否允许。 +3. 云安全组是否允许。 +4. 网络 ACL 是否允许。 +5. 客户端源 IP 是否在允许范围内。 + +Linux: + +```bash +ss -tulnp | grep ':80' +firewall-cmd --list-all 2>/dev/null +ufw status 2>/dev/null +``` + +## 负载均衡排查 + +重点检查: + +- 后端服务器是否加入负载均衡。 +- 后端端口是否正确。 +- 健康检查路径是否正确。 +- 健康检查协议是否匹配 HTTP/TCP/HTTPS。 +- 证书是否绑定正确。 +- 后端安全组是否允许负载均衡访问。 + +后端机器检查: + +```bash +# 本机访问 +curl -I http://127.0.0.1: + +# 从同网段机器访问 +curl -I http://: + +# 查看访问日志 +tail -f /var/log/nginx/access.log +``` + +## NAT 与公网访问 + +常见问题: + +- 云服务器没有公网 IP。 +- 出口依赖 NAT 网关但路由未配置。 +- 安全组只允许入站，不允许出站。 +- DNS 解析到错误地址。 + +排查命令: + +```bash +curl -I https://example.com +curl ifconfig.me +ip route +nslookup example.com +``` + +## 云盘与快照 + +```bash +# 查看磁盘 +lsblk +df -h + +# 查看文件系统 +blkid + +# 查看挂载 +findmnt +``` + +建议: + +- 扩容云盘后，还需要在系统内扩分区或文件系统。 +- 做高危磁盘操作前先创建快照。 +- 不要只在控制台扩容后就认为系统内空间已扩大。 + +## 快速定位表 + +| 现象 | 优先排查 | +| --- | --- | +| 公网访问不通 | 安全组、公网 IP、负载均衡、应用监听 | +| 内网访问不通 | 路由、安全组、本机防火墙 | +| 负载均衡健康检查失败 | 后端端口、健康检查路径、安全组 | +| 服务器能访问 IP 不能访问域名 | DNS、NAT、出站规则 | +| 云盘扩容后空间不变 | 分区和文件系统扩容 | diff --git a/docs/manual/cross-platform/PYTHON-NODE-SCRIPTS.md b/docs/manual/cross-platform/PYTHON-NODE-SCRIPTS.md new file mode 100644 index 0000000..292ae14 --- /dev/null +++ b/docs/manual/cross-platform/PYTHON-NODE-SCRIPTS.md @@ -0,0 +1,149 @@ +# Python 与 Node.js 跨平台脚本 + +这个专题从主手册迁移 Python 和 Node.js 跨平台脚本示例，用于系统信息收集、文件遍历和跨平台路径处理。 + +## Python 系统信息收集 + +```python +#!/usr/bin/env python3 +import json +import os +import platform +import subprocess +import sys +from datetime import datetime + +def get_system_info(): + return { + "timestamp": datetime.now().isoformat(), + "system": { + "os": platform.system(), + "os_version": platform.version(), + "architecture": platform.architecture(), + "machine": platform.machine(), + "processor": platform.processor(), + "hostname": platform.node(), + }, + "python": { + "version": sys.version, + "implementation": platform.python_implementation(), + "compiler": platform.python_compiler(), + "executable": sys.executable, + }, + "environment": dict(os.environ), + } + +def run_command(cmd, shell=True): + try: + result = subprocess.run( + cmd, + shell=shell, + capture_output=True, + text=True, + timeout=30, + ) + return { + "success": result.returncode == 0, + "returncode": result.returncode, + "stdout": result.stdout.strip(), + "stderr": result.stderr.strip(), + } + except Exception as exc: + return {"success": False, "error": str(exc)} + +def main(): + info = get_system_info() + print(f"OS: {info['system']['os']} {info['system']['os_version']}") + print(f"Hostname: {info['system']['hostname']}") + print(f"Architecture: {info['system']['architecture'][0]}") + print(f"Python: {info['python']['version'].split()[0]}") + + with open("system_info.json", "w", encoding="utf-8") as file: + json.dump(info, file, indent=2, ensure_ascii=False) + + print("Saved to system_info.json") + return 0 + +if __name__ == "__main__": + sys.exit(main()) +``` + +安全提醒: 环境变量可能包含敏感信息，公开报告前需要脱敏。 + +## Node.js 文件扫描 + +```javascript +#!/usr/bin/env node + +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +function formatBytes(bytes) { + if (bytes === 0) return '0 Bytes'; + const k = 1024; + const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB']; + const i = Math.floor(Math.log(bytes) / Math.log(k)); + return `${Math.round((bytes / Math.pow(k, i)) * 100) / 100} ${sizes[i]}`; +} + +function walkDir(dir, callback) { + const files = fs.readdirSync(dir); + for (const file of files) { + const fullPath = path.join(dir, file); + const stat = fs.statSync(fullPath); + if (stat.isDirectory()) { + walkDir(fullPath, callback); + } else { + callback(fullPath, stat); + } + } +} + +console.log('System information:'); +console.log(` OS: ${os.type()} ${os.release()}`); +console.log(` Arch: ${os.arch()}`); +console.log(` Hostname: ${os.hostname()}`); +console.log(` CPU cores: ${os.cpus().length}`); +console.log(` Memory: ${formatBytes(os.totalmem())}`); + +const currentDir = process.cwd(); +const largeFiles = []; + +walkDir(currentDir, (filePath, stat) => { + if (stat.size > 1024 * 1024) { + largeFiles.push({ + path: filePath, + size: stat.size, + sizeFormatted: formatBytes(stat.size), + }); + } +}); + +largeFiles.sort((a, b) => b.size - a.size); +largeFiles.slice(0, 10).forEach((file, index) => { + console.log(`${index + 1}. ${file.sizeFormatted} - ${path.relative(currentDir, file.path)}`); +}); +``` + +## 跨平台路径建议 + +- Python 使用 `pathlib.Path`。 +- Node.js 使用 `path.join`。 +- PowerShell 使用 `Join-Path`。 +- 不要在脚本里硬编码 `/` 或 `\`。 + +## 常用工具推荐 + +| 工具 | 描述 | Windows | Linux | macOS | +| --- | --- | --- | --- | --- | +| Git | 版本控制 | Yes | Yes | Yes | +| VS Code | 代码编辑器 | Yes | Yes | Yes | +| Docker | 容器化 | Yes | Yes | Yes | +| Node.js | JavaScript 运行时 | Yes | Yes | Yes | +| Python | 编程语言 | Yes | Yes | Yes | +| curl | HTTP 客户端 | Yes | Yes | Yes | +| jq | JSON 处理 | Yes | Yes | Yes | +| fzf | 模糊查找 | Yes | Yes | Yes | +| ripgrep | 快速搜索 | Yes | Yes | Yes | +| fd | 快速文件查找 | Yes | Yes | Yes | diff --git a/docs/manual/cross-platform/TOOLS.md b/docs/manual/cross-platform/TOOLS.md new file mode 100644 index 0000000..33f1c48 --- /dev/null +++ b/docs/manual/cross-platform/TOOLS.md @@ -0,0 +1,139 @@ +# 跨平台脚本与工具 + +跨平台运维建议优先选择在 Windows、Linux 和 CI 环境都容易运行的工具，例如 PowerShell 7、Python、Node.js、Git、curl、Docker。 + +## 常用工具 + +| 工具 | 适用场景 | Windows | Linux | macOS | +| --- | --- | --- | --- | --- | +| PowerShell 7 | 跨平台脚本和系统管理 | 支持 | 支持 | 支持 | +| Python | 自动化、文本处理、接口调用 | 支持 | 支持 | 支持 | +| Node.js | 前端工具链、轻量脚本 | 支持 | 支持 | 支持 | +| Git | 版本控制和协作 | 支持 | 支持 | 支持 | +| Docker | 环境封装和一致性运行 | 支持 | 支持 | 支持 | +| curl | HTTP 请求测试 | 支持 | 支持 | 支持 | +| wget | 下载和镜像同步 | 支持 | 支持 | 支持 | +| jq | JSON 处理 | 支持 | 支持 | 支持 | +| fzf | 交互式模糊查找 | 支持 | 支持 | 支持 | +| ripgrep | 快速文本搜索 | 支持 | 支持 | 支持 | +| fd | 快速文件查找 | 支持 | 支持 | 支持 | +| bat | 带语法高亮的 cat 替代 | 支持 | 支持 | 支持 | +| exa/eza | 现代 ls 替代 | 支持 | 支持 | 支持 | +| starship | 跨平台 Shell 提示符 | 支持 | 支持 | 支持 | + +## 按场景选择 + +| 场景 | 推荐工具 | +| --- | --- | +| 文件同步 | `rsync`、`scp`、`sftp`、Git | +| 远程连接 | OpenSSH、PowerShell Remoting、Windows Terminal | +| 压缩解压 | `tar`、`zip`、`7z` | +| 文本处理 | `rg`、`jq`、`awk`、PowerShell pipeline | +| 网络诊断 | `curl`、`wget`、`ping`、`traceroute`、`mtr` | +| 自动化脚本 | PowerShell 7、Python、Node.js、Bash | + +## PowerShell 跨平台建议 + +```powershell +# 查看 PowerShell 版本 +$PSVersionTable + +# 使用 Join-Path 处理路径 +Join-Path $HOME "logs" +``` + +## Python 跨平台建议 + +```python +from pathlib import Path + +log_dir = Path.home() / "logs" +print(log_dir) +``` + +## 路径处理建议 + +- 不要在脚本里硬编码 `/` 或 `\`。 +- PowerShell 使用 `Join-Path`。 +- Python 使用 `pathlib`。 +- Node.js 使用 `path.join`。 + +## 文件同步 + +```bash +# Linux/macOS 常用 +rsync -avz ./dist/ user@server:/opt/app/ +scp file.txt user@server:/tmp/ +sftp user@server +``` + +```powershell +# PowerShell 跨平台复制 +Copy-Item .\dist\* \\server\share\dist -Recurse +``` + +## 文本和 JSON 处理 + +```bash +# 快速搜索 +rg "error|failed" logs/ + +# JSON 提取 +curl -s https://example.com/api | jq '.items[] | {name, status}' + +# 查找文件 +fd "\.log$" /var/log +``` + +```powershell +# PowerShell 对象管道 +Get-Process | Sort-Object CPU -Descending | Select-Object -First 10 + +# JSON 转对象 +Get-Content report.json -Raw | ConvertFrom-Json +``` + +## 压缩解压 + +```bash +# tar +tar -czf logs.tar.gz logs/ +tar -xzf logs.tar.gz + +# zip +zip -r archive.zip folder/ +unzip archive.zip +``` + +```powershell +Compress-Archive -Path .\logs -DestinationPath logs.zip +Expand-Archive -Path logs.zip -DestinationPath .\logs-out +``` + +## 网络诊断 + +```bash +# HTTP 调试 +curl -I https://example.com +curl -v https://example.com + +# 下载 +wget https://example.com/file.tar.gz + +# 路由和链路 +ping example.com +traceroute example.com +mtr example.com +``` + +## 推荐原则 + +- 能用结构化对象就不要只解析纯文本，例如 PowerShell 对象、JSON、CSV。 +- 团队脚本优先选择依赖少、安装简单、Windows/Linux 都可运行的工具。 +- 在 CI 中固定工具版本，避免不同机器行为不一致。 +- 面向新同事的脚本要写清楚依赖、输入、输出和失败处理。 + +## 延伸阅读 + +- [示例脚本](https://github.com/shiwenxin123/PowerShell-Linux-/tree/main/scripts) +- [PowerShell 与 Bash 命令对照](../../POWERSHELL-BASH-COMPARISON.md) diff --git a/docs/manual/devtools/GIT-SSH-CURL-JQ.md b/docs/manual/devtools/GIT-SSH-CURL-JQ.md new file mode 100644 index 0000000..bbb6aa2 --- /dev/null +++ b/docs/manual/devtools/GIT-SSH-CURL-JQ.md @@ -0,0 +1,153 @@ +# Git、SSH、curl 与 jq + +这些工具常用于开发协作、接口排查、远程登录、自动化脚本和日志分析。它们不是系统命令的边角料，而是日常排障的主力工具。 + +## Git 常用命令 + +```bash +# 查看状态 +git status + +# 查看分支 +git branch + +# 查看远程 +git remote -v + +# 拉取更新 +git pull + +# 提交 +git add . +git commit -m "docs: update commands" + +# 查看历史 +git log --oneline --decorate -n 10 + +# 查看差异 +git diff +git diff --staged +``` + +## Git 排查 + +```bash +# 查看当前配置 +git config --list + +# 查看某个文件历史 +git log -- path/to/file + +# 查看某次提交 +git show + +# 查看远程分支 +git branch -r +``` + +常见问题: + +- 没有权限 push。 +- 远程地址错误。 +- 本地分支落后远程。 +- 冲突未解决。 + +## SSH key + +```bash +# 生成密钥 +ssh-keygen -t ed25519 -C "your_email@example.com" + +# 查看公钥 +cat ~/.ssh/id_ed25519.pub + +# 测试 GitHub SSH +ssh -T git@github.com + +# 指定密钥连接 +ssh -i ~/.ssh/id_ed25519 user@host +``` + +安全提醒: + +- 不要提交私钥。 +- 不要把私钥粘贴到 Issue 或聊天窗口。 +- 公钥可以公开，私钥必须保密。 + +## curl + +```bash +# 查看响应头 +curl -I https://example.com + +# GET 请求 +curl https://example.com/api + +# POST JSON +curl -X POST https://example.com/api \ + -H "Content-Type: application/json" \ + -d '{"name":"demo"}' + +# 显示详细连接过程 +curl -v https://example.com + +# 跟随重定向 +curl -L https://example.com +``` + +排查建议: + +- 连接失败看 DNS、网络、防火墙。 +- 证书失败看证书链和系统时间。 +- 502/504 看代理和后端服务。 + +## jq + +```bash +# 格式化 JSON +cat data.json | jq . + +# 取字段 +cat data.json | jq '.name' + +# 取数组 +cat data.json | jq '.items[]' + +# 过滤 +cat data.json | jq '.items[] | select(.status=="running")' +``` + +结合 curl: + +```bash +curl -s https://example.com/api | jq . +``` + +## tar/zip + +```bash +# 打包 +tar -czf logs.tar.gz /var/log/app + +# 解包 +tar -xzf logs.tar.gz + +# zip 压缩 +zip -r logs.zip logs/ + +# unzip 解压 +unzip logs.zip +``` + +## 常用组合 + +```bash +# 拉取接口 JSON 并过滤字段 +curl -s https://example.com/api | jq '.data[] | {id,name,status}' + +# 打包日志用于排查 +tar -czf app-logs.tar.gz /var/log/app + +# 查看最近提交修改了哪些文件 +git show --name-only --oneline +``` diff --git a/docs/manual/devtools/README.md b/docs/manual/devtools/README.md new file mode 100644 index 0000000..e3b090d --- /dev/null +++ b/docs/manual/devtools/README.md @@ -0,0 +1,9 @@ +# 开发与排障工具 + +这个目录整理开发、协作、接口排查和自动化脚本中常用的工具命令。 + +## 专题 + +| 专题 | 文档 | +| --- | --- | +| Git、SSH、curl 与 jq | [Git、SSH、curl 与 jq](GIT-SSH-CURL-JQ.md) | diff --git a/docs/manual/ha/KEEPALIVED.md b/docs/manual/ha/KEEPALIVED.md new file mode 100644 index 0000000..a5f3350 --- /dev/null +++ b/docs/manual/ha/KEEPALIVED.md @@ -0,0 +1,142 @@ +# Keepalived 高可用 + +Keepalived 常用于通过 VRRP 提供虚拟 IP，实现主备切换。生产环境配置前要确认网卡名、VIP、路由、安全组和健康检查脚本。 + +## 安装 + +```bash +# Debian/Ubuntu/UOS 兼容环境 +sudo apt install keepalived + +# RPM/YUM 兼容环境 +sudo yum install keepalived +``` + +## 主配置文件 + +```bash +sudo vi /etc/keepalived/keepalived.conf +``` + +## 主节点示例 + +```text +global_defs { + router_id LVS_MASTER + enable_script_security + script_user root +} + +vrrp_script check_nginx { + script "/etc/keepalived/check_nginx.sh" + interval 2 + weight -20 + fall 3 + rise 2 +} + +vrrp_instance VI_1 { + state MASTER + interface eth0 + virtual_router_id 51 + priority 100 + advert_int 1 + authentication { + auth_type PASS + auth_pass 1111 + } + virtual_ipaddress { + 192.168.1.200/24 dev eth0 label eth0:0 + } + track_script { + check_nginx + } + notify_master "/etc/keepalived/notify.sh master" + notify_backup "/etc/keepalived/notify.sh backup" + notify_fault "/etc/keepalived/notify.sh fault" +} +``` + +## 备用节点示例 + +```text +global_defs { + router_id LVS_BACKUP +} + +vrrp_instance VI_1 { + state BACKUP + interface eth0 + virtual_router_id 51 + priority 90 + advert_int 1 + authentication { + auth_type PASS + auth_pass 1111 + } + virtual_ipaddress { + 192.168.1.200/24 dev eth0 label eth0:0 + } + track_script { + check_nginx + } +} +``` + +## 健康检查脚本 + +```bash +sudo tee /etc/keepalived/check_nginx.sh >/dev/null <<'EOF' +#!/bin/bash +if ! curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1/health | grep -q "200"; then + exit 1 +fi +exit 0 +EOF + +sudo chmod +x /etc/keepalived/check_nginx.sh +``` + +## 通知脚本 + +```bash +sudo tee /etc/keepalived/notify.sh >/dev/null <<'EOF' +#!/bin/bash +TYPE=$1 +NAME=$2 +STATE=$3 +DATE=$(date '+%Y-%m-%d %H:%M:%S') +echo "$DATE - $TYPE - $NAME - $STATE" >> /var/log/keepalived-notify.log +EOF + +sudo chmod +x /etc/keepalived/notify.sh +``` + +## 服务管理 + +```bash +sudo systemctl enable keepalived +sudo systemctl start keepalived +systemctl status keepalived + +# 查看 VIP +ip addr show eth0 + +# 查看日志 +journalctl -u keepalived -f +``` + +## 排查要点 + +- 主备节点 `virtual_router_id` 必须一致。 +- 主备节点优先级应不同。 +- VIP 不能与现有 IP 冲突。 +- 网卡名必须和实际环境一致。 +- 云环境可能需要在控制台允许 VIP 或配置高可用虚拟 IP。 +- 健康检查脚本必须可执行，且退出码正确。 + +## 高危提醒 + +- 切换 VIP 会影响业务入口，建议在维护窗口测试。 +- 修改 VRRP 配置前备份 `/etc/keepalived/keepalived.conf`。 +- 不要在未确认云平台支持的情况下直接使用传统 VIP 漂移方案。 diff --git a/docs/manual/kubernetes/ADVANCED-TROUBLESHOOTING.md b/docs/manual/kubernetes/ADVANCED-TROUBLESHOOTING.md new file mode 100644 index 0000000..a499b3f --- /dev/null +++ b/docs/manual/kubernetes/ADVANCED-TROUBLESHOOTING.md @@ -0,0 +1,144 @@ +# Kubernetes 进阶排查 + +Kubernetes 排查建议按资源链路推进: Pod -> Service -> Endpoints -> Ingress -> Node -> Storage -> Helm Release。 + +## 上下文与命名空间 + +```bash +# 当前上下文 +kubectl config current-context + +# 所有上下文 +kubectl config get-contexts + +# 查看命名空间 +kubectl get ns +``` + +## Pod 与事件 + +```bash +# 查看 Pod +kubectl get pods -n -o wide + +# 查看详情 +kubectl describe pod -n + +# 查看事件 +kubectl get events -n --sort-by=.lastTimestamp + +# 查看日志 +kubectl logs -n +kubectl logs -c -n +``` + +## Service 与 Endpoints + +```bash +# 查看 Service +kubectl get svc -n + +# 查看 Endpoints +kubectl get endpoints -n + +# 查看 EndpointSlice +kubectl get endpointslice -n + +# 查看 Service 详情 +kubectl describe svc -n +``` + +排查重点: + +- Service selector 是否匹配 Pod labels。 +- targetPort 是否和容器监听端口一致。 +- Endpoints 是否为空。 + +## Ingress + +```bash +# 查看 Ingress +kubectl get ingress -n + +# 查看 Ingress 详情 +kubectl describe ingress -n + +# 查看 Ingress Controller Pod +kubectl get pods -A | grep -i ingress +``` + +排查重点: + +- Host、Path、ServiceName、ServicePort 是否正确。 +- TLS Secret 是否存在。 +- Ingress Controller 是否正常运行。 + +## 存储 PVC/PV + +```bash +# 查看 PVC +kubectl get pvc -n + +# 查看 PV +kubectl get pv + +# 查看 StorageClass +kubectl get storageclass + +# 查看 PVC 详情 +kubectl describe pvc -n +``` + +常见问题: + +- PVC Pending。 +- StorageClass 不存在。 +- 动态供给失败。 +- 节点无法挂载卷。 + +## Node 排查 + +```bash +# 查看节点 +kubectl get nodes -o wide + +# 查看节点详情 +kubectl describe node + +# 查看节点资源 +kubectl top node + +# 查看 Pod 资源 +kubectl top pod -A +``` + +## Helm + +```bash +# 查看 Release +helm list -A + +# 查看状态 +helm status -n + +# 查看历史 +helm history -n + +# 回滚 +helm rollback -n +``` + +## 常见现象对应入口 + +| 现象 | 优先排查 | +| --- | --- | +| Pod 无法启动 | `describe pod`、`logs`、`events` | +| Service 不通 | `svc`、`endpoints`、labels、targetPort | +| Ingress 404/502 | Ingress 规则、Service、Controller 日志 | +| PVC Pending | PVC、PV、StorageClass、存储插件 | +| 发布失败 | Helm status、history、values | + +延伸案例: + +- [Pod CrashLoopBackOff 排查](../../cases/K8S-CRASHLOOPBACKOFF.md) +- [ImagePullBackOff 排查](../../cases/K8S-IMAGEPULLBACKOFF.md) diff --git a/docs/manual/kubernetes/DOCKER-K8S-PRODUCTION.md b/docs/manual/kubernetes/DOCKER-K8S-PRODUCTION.md new file mode 100644 index 0000000..e8c093d --- /dev/null +++ b/docs/manual/kubernetes/DOCKER-K8S-PRODUCTION.md @@ -0,0 +1,164 @@ +# Docker 与 Kubernetes 生产级命令 + +这个专题从主手册迁移容器与 Kubernetes 生产级命令，覆盖镜像、容器、资源限制、健康检查、Compose、Deployment、Service、ConfigMap、Secret 和节点维护。 + +## Docker 镜像管理 + +```bash +docker images +docker pull nginx:alpine +docker build -t myapp:v1 . +docker tag myapp:v1 registry.example.com/myapp:v1 +docker push registry.example.com/myapp:v1 +docker rmi nginx:alpine +docker image prune -a +``` + +## Docker 容器管理 + +```bash +docker run -d --name nginx -p 80:80 --restart=always --memory=512m --cpus=0.5 nginx:alpine +docker ps +docker ps -a +docker logs nginx +docker logs -f --tail=100 nginx +docker inspect nginx +docker exec -it nginx sh +docker cp file.txt nginx:/path/ +docker cp nginx:/path/file.txt . +docker stop nginx +docker start nginx +docker restart nginx +docker rm -f nginx +docker container prune +``` + +## Docker 资源限制与健康检查 + +```bash +docker run -d \ + --name myapp \ + --memory=1g \ + --memory-reservation=800m \ + --cpus=1 \ + --ulimit nofile=65536:65536 \ + --health-cmd="curl -f http://localhost/health || exit 1" \ + --health-interval=10s \ + --health-timeout=5s \ + --health-retries=3 \ + myapp:v1 +``` + +## Docker 网络与存储 + +```bash +# 网络 +docker network create --driver bridge mynet +docker network ls +docker network inspect mynet +docker network connect mynet nginx +docker network disconnect mynet nginx + +# 存储 +docker volume create myvol +docker volume ls +docker volume inspect myvol +docker run -v myvol:/data nginx +docker volume prune +``` + +## Docker Compose + +```bash +docker compose up -d +docker compose ps +docker compose logs -f +docker compose config +docker compose down +``` + +高危提醒: `docker compose down -v` 会删除 volume，生产环境谨慎执行。 + +## Kubernetes 集群信息 + +```bash +kubectl version --short +kubectl cluster-info +kubectl get nodes -o wide +kubectl top nodes +kubectl top pods +``` + +## Namespace + +```bash +kubectl get namespaces +kubectl create namespace production +kubectl config set-context --current --namespace=production +``` + +## Pod 管理 + +```bash +kubectl get pods -o wide +kubectl get pods --show-labels +kubectl describe pod +kubectl logs +kubectl logs -f --tail=100 +kubectl logs -f -c +kubectl exec -it -- sh +kubectl port-forward 8080:80 +kubectl cp file.txt :/path/ +kubectl delete pod +``` + +## Deployment 发布与回滚 + +```bash +kubectl apply -f deployment.yml +kubectl get deployments +kubectl rollout status deployment/nginx +kubectl rollout history deployment/nginx +kubectl set image deployment/nginx nginx=nginx:1.26-alpine +kubectl rollout undo deployment/nginx +kubectl scale deployment/nginx --replicas=5 +kubectl autoscale deployment/nginx --min=3 --max=10 --cpu-percent=80 +``` + +## Service + +```bash +kubectl get services +kubectl expose deployment nginx --port=80 --target-port=80 --type=ClusterIP +kubectl expose deployment nginx --port=80 --target-port=80 --type=NodePort +kubectl expose deployment nginx --port=80 --target-port=80 --type=LoadBalancer +``` + +## ConfigMap 与 Secret + +```bash +kubectl create configmap nginx-config --from-file=nginx.conf +kubectl create secret generic db-secret --from-literal=username=admin --from-literal=password=secret +kubectl get configmaps +kubectl get secrets +``` + +安全提醒: Secret 示例只适合演示。生产环境不要在命令历史或明文 YAML 中暴露真实密码。 + +## 事件、调试与节点维护 + +```bash +kubectl get events --sort-by='.lastTimestamp' +kubectl api-resources +kubectl explain deployment.spec +kubectl debug -it --image=busybox --share-processes +kubectl cordon +kubectl drain --ignore-daemonsets --delete-emptydir-data +kubectl uncordon +``` + +延伸阅读: + +- [Docker 与 Kubernetes 运维速查](../../containers/DOCKER-KUBERNETES-CHEATSHEET.md) +- [Kubernetes 进阶排查](ADVANCED-TROUBLESHOOTING.md) +- [Docker Compose 启动失败排查](../../cases/DOCKER-COMPOSE-FAILED.md) diff --git a/docs/manual/linux/BASIC.md b/docs/manual/linux/BASIC.md new file mode 100644 index 0000000..48c158c --- /dev/null +++ b/docs/manual/linux/BASIC.md @@ -0,0 +1,83 @@ +# Linux 基础命令 + +这个页面整理 Linux 日常操作中最常见的目录、文件、文本和进程命令。 + +## 目录导航 + +```bash +# 查看当前目录 +pwd + +# 切换目录 +cd /var/log + +# 返回上级目录 +cd .. + +# 返回上一次目录 +cd - +``` + +## 文件与目录 + +```bash +# 列出文件 +ls -la + +# 创建目录 +mkdir demo + +# 创建文件 +touch notes.txt + +# 复制文件 +cp source.txt dest.txt + +# 复制目录 +cp -r source_dir dest_dir + +# 移动或重命名 +mv old.txt new.txt +``` + +## 查看与搜索 + +```bash +# 查看文件 +cat file.txt + +# 查看前 20 行 +head -n 20 file.txt + +# 查看后 100 行 +tail -n 100 app.log + +# 实时查看日志 +tail -f app.log + +# 搜索关键字 +grep -R "error" /var/log +``` + +## 进程与资源 + +```bash +# 查看进程 +ps aux + +# 实时资源 +top + +# 内存 +free -h + +# 磁盘空间 +df -h + +# 目录占用 +du -sh /var/log +``` + +## 安全提醒 + +`rm -rf`、`chmod -R`、`chown -R` 等命令影响范围大，执行前请查看 [命令风险等级说明](../../security/RISK-LEVELS.md)。 diff --git a/docs/manual/linux/DISK-LVM.md b/docs/manual/linux/DISK-LVM.md new file mode 100644 index 0000000..80b91ca --- /dev/null +++ b/docs/manual/linux/DISK-LVM.md @@ -0,0 +1,116 @@ +# Linux 磁盘、挂载与 LVM + +磁盘操作风险较高。涉及分区、格式化、挂载和扩容前，必须确认设备名、挂载点、文件系统类型和备份状态。 + +## 查看磁盘与文件系统 + +```bash +# 查看块设备 +lsblk + +# 查看文件系统和 UUID +blkid + +# 查看磁盘空间 +df -h + +# 查看 inode +df -i + +# 查看挂载 +mount +findmnt +``` + +## 查看目录占用 + +```bash +# 查看一级目录占用 +du -sh /* 2>/dev/null | sort -h + +# 查找大文件 +find / -type f -size +500M 2>/dev/null + +# 查看被进程占用的已删除文件 +lsof | grep deleted +``` + +## 挂载与卸载 + +```bash +# 创建挂载目录 +sudo mkdir -p /data + +# 临时挂载 +sudo mount /dev/sdb1 /data + +# 卸载 +sudo umount /data + +# 查看 fstab +cat /etc/fstab +``` + +建议使用 UUID 写入 `/etc/fstab`: + +```text +UUID= /data ext4 defaults 0 2 +``` + +修改后先测试: + +```bash +sudo mount -a +``` + +## LVM 查看 + +```bash +# 物理卷 +pvs +pvdisplay + +# 卷组 +vgs +vgdisplay + +# 逻辑卷 +lvs +lvdisplay +``` + +## LVM 扩容示例 + +风险等级: 高 + +```bash +# 查看当前逻辑卷 +lvs + +# 扩展逻辑卷 +sudo lvextend -L +10G /dev/vg0/lv_data + +# ext4 文件系统扩容 +sudo resize2fs /dev/vg0/lv_data + +# xfs 文件系统扩容 +sudo xfs_growfs /data +``` + +## 常见问题 + +| 现象 | 排查 | +| --- | --- | +| 磁盘满 | `df -h`、`du -sh`、`find` | +| inode 满 | `df -i` | +| 删除文件空间不释放 | `lsof \| grep deleted` | +| 开机挂载失败 | `/etc/fstab`、`mount -a` | +| 设备名变化 | 使用 UUID 挂载 | + +## 高危提醒 + +- `mkfs.*` 会格式化文件系统，执行前必须确认设备。 +- `fdisk`、`parted` 会修改分区表，生产环境需备份。 +- 不要在不了解用途时删除数据库、容器 volume、业务上传目录。 + +延伸案例: [磁盘空间满排查](../../cases/DISK-FULL.md)。 diff --git a/docs/manual/linux/MONITORING-LOGS.md b/docs/manual/linux/MONITORING-LOGS.md new file mode 100644 index 0000000..d732a21 --- /dev/null +++ b/docs/manual/linux/MONITORING-LOGS.md @@ -0,0 +1,113 @@ +# Linux 系统监控与日志 + +这个专题从主手册迁移 Linux 系统监控与日志相关内容，覆盖资源查看、硬件信息、systemd 日志、内核日志和传统日志文件。 + +## 系统资源 + +```bash +# 实时监控系统资源 +top + +# 更强的交互式监控 +htop + +# 内存 +free -h + +# 磁盘 +df -h + +# 目录大小 +du -sh /path/to/dir + +# 平均负载 +uptime +``` + +## 硬件信息 + +```bash +# CPU 信息 +lscpu + +# PCI 设备 +lspci + +# USB 设备 +lsusb + +# 硬件信息 +lshw +``` + +## systemd 日志 + +```bash +# 显示系统日志 +journalctl + +# 最近 100 条 +journalctl -n 100 + +# 实时监控 +journalctl -f + +# 指定服务 +journalctl -u nginx + +# 今天的日志 +journalctl --since today + +# 指定时间段 +journalctl --since "2026-03-13 09:00:00" --until "2026-03-13 17:00:00" +``` + +## 内核日志 + +```bash +# 显示内核日志 +dmesg + +# 实时监控内核日志 +dmesg -w + +# 查看 OOM 记录 +dmesg -T | grep -i "out of memory" +``` + +## 传统日志文件 + +```bash +# Debian/Ubuntu/UOS 常见日志 +cat /var/log/syslog +cat /var/log/auth.log +cat /var/log/kern.log + +# RHEL/Kylin 常见日志 +cat /var/log/messages +cat /var/log/secure +``` + +## 常见排查组合 + +```bash +# CPU 高 +ps aux --sort=-%cpu | head -n 10 + +# 内存高 +ps aux --sort=-%mem | head -n 10 + +# 磁盘满 +df -h +du -sh /* 2>/dev/null | sort -h + +# 已删除但仍占用空间的文件 +lsof | grep deleted +``` + +延伸阅读: + +- [Linux 故障应急排查清单](../../troubleshooting/LINUX-INCIDENT-CHECKLIST.md) +- [日志轮转、审计与系统日志](../security/LOGGING-AUDIT.md) +- [CPU 飙高排查](../../cases/CPU-HIGH.md) +- [磁盘空间满排查](../../cases/DISK-FULL.md) diff --git a/docs/manual/linux/NETWORK.md b/docs/manual/linux/NETWORK.md new file mode 100644 index 0000000..19a91c0 --- /dev/null +++ b/docs/manual/linux/NETWORK.md @@ -0,0 +1,156 @@ +# Linux 网络排查 + +网络问题建议按顺序排查: 本机 IP、路由、DNS、端口监听、防火墙、远端连通性。 + +## 本机网络 + +```bash +# 查看 IP +ip addr +ip addr show +ip a + +# 查看接口统计 +ip -s link + +# 查看路由 +ip route +ip route show +ip r + +# 查看 DNS +cat /etc/resolv.conf + +# 启用/禁用接口 +ip link set eth0 up +ip link set eth0 down +``` + +## 连通性测试 + +```bash +# 测试 IP 连通 +ping 8.8.8.8 + +# 测试域名解析和连通 +ping example.com + +# 测试端口 +nc -vz example.com 443 + +# HTTP 请求 +curl -I https://example.com + +# 路由跟踪 +traceroute example.com + +# 连通性和丢包分析 +mtr example.com + +# DNS 查询 +nslookup example.com +dig example.com +dig example.com MX +``` + +## 端口与连接 + +```bash +# 查看监听端口 +ss -tulnp +ss -tuln + +# 查看 TCP 连接 +ss -tan +ss -tupa +ss -tupn + +# 查看指定端口 +ss -tulnp | grep ':8080' + +# 传统工具 +netstat -tuln +``` + +## 文件传输 + +```bash +# 复制文件到远程服务器 +scp local_file.txt user@remote:/path/to/dest/ + +# 从远程服务器复制文件 +scp user@remote:/path/to/remote_file.txt /local/dest/ + +# 复制目录 +scp -r local_dir user@remote:/path/to/dest/ + +# 交互式传输 +sftp user@remote + +# rsync 同步文件 +rsync -avz local_file.txt user@remote:/path/to/dest/ + +# rsync 同步目录 +rsync -avz local_dir/ user@remote:/path/to/dest/ + +# 显示进度 +rsync -avz --progress local_dir/ user@remote:/path/to/dest/ + +# 删除目标中源位置没有的文件 +rsync -avz --delete local_dir/ user@remote:/path/to/dest/ +``` + +## SSH 远程登录 + +```bash +# 基本登录 +ssh user@remote_host + +# 使用非标准端口 +ssh -p 2222 user@remote_host + +# 使用私钥 +ssh -i /path/to/private_key user@remote_host + +# 生成密钥 +ssh-keygen -t ed25519 -C "your_email@example.com" + +# 复制公钥 +ssh-copy-id user@remote_host + +# 本地端口转发 +ssh -L 8080:localhost:80 user@remote_host + +# 远程端口转发 +ssh -R 9000:localhost:3000 user@remote_host + +# 动态转发 +ssh -D 1080 user@remote_host +``` + +`~/.ssh/config` 示例: + +```text +Host myserver + HostName 192.168.1.100 + User username + Port 2222 + IdentityFile ~/.ssh/myserver_key +``` + +## 防火墙 + +```bash +# firewalld 状态 +firewall-cmd --state +firewall-cmd --list-all + +# ufw 状态 +ufw status +``` + +## 延伸案例 + +- [端口被占用排查](../../cases/PORT-IN-USE.md) +- [SSH 连接失败排查](../../cases/SSH-CONNECTION-FAILED.md) +- [常见报错排查](../../troubleshooting/COMMON-ERRORS.md) diff --git a/docs/manual/linux/PACKAGE-MANAGEMENT.md b/docs/manual/linux/PACKAGE-MANAGEMENT.md new file mode 100644 index 0000000..5a8fdd1 --- /dev/null +++ b/docs/manual/linux/PACKAGE-MANAGEMENT.md @@ -0,0 +1,128 @@ +# Linux 包管理 + +Linux 包管理要先判断发行版和包格式，再选择 `apt/dpkg` 或 `yum/dnf/rpm`。国产 Linux 环境还要额外确认系统版本、CPU 架构和软件源。 + +## 判断系统和架构 + +```bash +cat /etc/os-release +uname -m + +# Debian/Ubuntu/UOS 兼容环境 +dpkg --print-architecture 2>/dev/null + +# RPM/YUM 兼容环境 +rpm --eval '%{_arch}' 2>/dev/null +``` + +## APT 常用命令 + +```bash +# 更新软件源索引 +sudo apt update + +# 安装软件 +sudo apt install + +# 升级软件 +sudo apt upgrade + +# 搜索软件 +apt search + +# 查看软件包信息 +apt show + +# 删除软件 +sudo apt remove + +# 删除软件和配置 +sudo apt purge +``` + +## DPKG 常用命令 + +```bash +# 查看已安装包 +dpkg -l | grep + +# 安装本地 deb 包 +sudo dpkg -i package.deb + +# 查看文件属于哪个包 +dpkg -S /path/to/file + +# 查看包安装了哪些文件 +dpkg -L +``` + +## YUM/DNF 常用命令 + +```bash +# 查看仓库 +yum repolist +dnf repolist + +# 安装软件 +sudo yum install +sudo dnf install + +# 搜索软件 +yum search +dnf search + +# 查看软件包信息 +yum info +dnf info + +# 删除软件 +sudo yum remove +sudo dnf remove +``` + +## RPM 常用命令 + +```bash +# 查看已安装包 +rpm -qa | grep + +# 安装 rpm 包 +sudo rpm -ivh package.rpm + +# 升级 rpm 包 +sudo rpm -Uvh package.rpm + +# 查看文件属于哪个包 +rpm -qf /path/to/file + +# 查看包安装了哪些文件 +rpm -ql +``` + +## 软件源排查 + +```bash +# APT 源 +cat /etc/apt/sources.list +ls /etc/apt/sources.list.d/ + +# YUM/DNF 源 +ls /etc/yum.repos.d/ +yum repolist -v +``` + +常见问题: + +- 软件源不可达。 +- 系统版本和软件源版本不匹配。 +- CPU 架构不匹配。 +- GPG key 或证书异常。 +- 内网环境 DNS 或代理配置错误。 + +## 离线安装建议 + +- 同一系统版本、同一架构准备软件包。 +- 复杂依赖优先建立内网软件源。 +- 不建议长期手工拷贝单个包。 + +延伸阅读: [国产 Linux 离线安装与软件源维护](../../domestic-linux/OFFLINE-PACKAGE-GUIDE.md)。 diff --git a/docs/manual/linux/PERFORMANCE-TUNING.md b/docs/manual/linux/PERFORMANCE-TUNING.md new file mode 100644 index 0000000..0b45030 --- /dev/null +++ b/docs/manual/linux/PERFORMANCE-TUNING.md @@ -0,0 +1,170 @@ +# Linux 性能调优 + +性能调优应先观测、再变更、最后回滚验证。生产环境不要直接套用模板参数，先确认内核版本、硬件类型、业务模型和基线指标。 + +## 调优前检查 + +```bash +# 系统与内核 +uname -a +cat /etc/os-release + +# CPU、内存、磁盘和网络概况 +lscpu +free -h +lsblk +ip addr + +# 当前负载 +uptime +top +vmstat 1 5 +iostat -x 1 5 +``` + +## 内核参数 + +```bash +# 查看当前参数 +sysctl net.core.somaxconn +sysctl net.ipv4.tcp_max_syn_backlog +sysctl vm.swappiness +sysctl fs.file-max + +# 临时设置，重启后失效 +sudo sysctl -w net.core.somaxconn=65535 +sudo sysctl -w vm.swappiness=10 + +# 持久配置 +sudo vi /etc/sysctl.conf +sudo sysctl -p +``` + +常见参数示例: + +```text +# TCP 队列和缓冲区 +net.core.somaxconn = 65535 +net.ipv4.tcp_max_syn_backlog = 65535 +net.core.rmem_max = 16777216 +net.core.wmem_max = 16777216 +net.ipv4.tcp_rmem = 4096 87380 16777216 +net.ipv4.tcp_wmem = 4096 65536 16777216 + +# TIME_WAIT 相关 +net.ipv4.tcp_tw_reuse = 1 +net.ipv4.tcp_fin_timeout = 30 + +# 文件描述符 +fs.file-max = 2097152 +fs.nr_open = 2097152 + +# 虚拟内存 +vm.swappiness = 10 +vm.dirty_ratio = 15 +vm.dirty_background_ratio = 5 +vm.vfs_cache_pressure = 50 +``` + +注意: `net.ipv4.tcp_tw_recycle` 已不适合现代生产环境，尤其容易和 NAT 场景冲突，不建议启用。 + +## limits 资源限制 + +```bash +# 查看当前限制 +ulimit -a +ulimit -n + +# 编辑 limits +sudo vi /etc/security/limits.conf +``` + +示例: + +```text +* soft nofile 655360 +* hard nofile 655360 +* soft nproc 655360 +* hard nproc 655360 + +root soft nofile 1048576 +root hard nofile 1048576 + +nginx soft nofile 1048576 +nginx hard nofile 1048576 +mysql soft nofile 1048576 +mysql hard nofile 1048576 +``` + +确认 PAM 已加载 limits: + +```bash +grep pam_limits /etc/pam.d/login +grep pam_limits /etc/pam.d/sshd +``` + +## 磁盘 I/O + +```bash +# 查看调度器 +cat /sys/block/sda/queue/scheduler + +# 临时修改调度器，需按实际设备名调整 +echo mq-deadline | sudo tee /sys/block/sda/queue/scheduler + +# 查看和调整预读 +sudo blockdev --getra /dev/sda +sudo blockdev --setra 8192 /dev/sda + +# 查看 I/O 统计 +iostat -x 1 + +# 查看进程 I/O +iotop + +# 设置进程 I/O 优先级 +ionice -c 2 -n 7 -p +ionice -c 3 -p +``` + +建议: + +- SSD/NVMe 优先评估 `none`、`mq-deadline`、`kyber`。 +- 机械盘可评估 `deadline`、`bfq`。 +- 永久调整调度器前，先确认发行版和内核支持方式。 + +## 网络连接排查 + +```bash +# 监听和连接情况 +ss -s +ss -ant +ss -tulnp + +# 路由和邻居表 +ip route +ip neigh + +# 网卡统计 +ip -s link +ethtool eth0 +``` + +高并发服务建议同时关注: + +- `somaxconn` 和应用 listen backlog 是否匹配。 +- 文件描述符是否足够。 +- 防火墙、负载均衡和应用连接池是否成为瓶颈。 + +## 变更建议 + +- 先记录基线，再改一个参数，最后复测。 +- 所有持久配置都应保留变更记录和回滚值。 +- 不同内核版本和发行版默认值差异较大，不建议照搬线上参数。 +- 数据库、消息队列和 Web 服务应优先参考对应产品官方调优建议。 + +## 延伸阅读 + +- [Linux 系统监控与日志](MONITORING-LOGS.md) +- [Linux 磁盘、挂载与 LVM](DISK-LVM.md) +- [命令风险等级说明](../../security/RISK-LEVELS.md) diff --git a/docs/manual/linux/SHELL-SCRIPTING.md b/docs/manual/linux/SHELL-SCRIPTING.md new file mode 100644 index 0000000..90b9f4a --- /dev/null +++ b/docs/manual/linux/SHELL-SCRIPTING.md @@ -0,0 +1,160 @@ +# Shell 脚本基础与高级技巧 + +这个专题从主手册迁移 Shell 脚本基础、控制流、函数、参数、错误处理和高级 Bash 技巧。 + +## 脚本基础 + +```bash +#!/bin/bash + +NAME="World" +NUMBER=42 +ARRAY=(1 2 3 4 5) + +echo "Hello, $NAME!" +echo "Number: $NUMBER" +echo "First array element: ${ARRAY[0]}" + +CURRENT_DIR=$(pwd) +echo "Current directory: $CURRENT_DIR" + +RESULT=$((3 + 4 * 2)) +echo "Result: $RESULT" +``` + +## 条件与文件测试 + +```bash +if [ "$NUMBER" -gt 40 ]; then + echo "Number is greater than 40" +elif [ "$NUMBER" -eq 40 ]; then + echo "Number is exactly 40" +else + echo "Number is less than 40" +fi + +if [ -f "file.txt" ]; then + echo "file.txt exists" +fi + +if [ -d "dir" ]; then + echo "dir exists" +fi +``` + +常用测试: + +- `-f`: 普通文件 +- `-d`: 目录 +- `-e`: 存在 +- `-r`: 可读 +- `-w`: 可写 +- `-x`: 可执行 +- `-s`: 大小大于 0 + +## 循环与 case + +```bash +for i in 1 2 3 4 5; do + echo "Iteration $i" +done + +for file in *.txt; do + echo "File: $file" +done + +for ((i=0; i<5; i++)); do + echo "Iteration $i" +done + +i=0 +while [ "$i" -lt 5 ]; do + echo "Iteration $i" + i=$((i + 1)) +done + +case "$NUMBER" in + 42) echo "The answer!" ;; + 40) echo "Exactly 40" ;; + *) echo "Something else" ;; +esac +``` + +## 函数与参数 + +```bash +greet() { + local name="$1" + echo "Hello, $name!" +} + +add() { + local a=$1 + local b=$2 + echo $((a + b)) +} + +greet "World" +result=$(add 3 4) +echo "Result: $result" + +echo "Script name: $0" +echo "First argument: $1" +echo "All arguments: $@" +echo "Number of arguments: $#" +``` + +## 脚本选项与错误处理 + +```bash +set -e +set -u +set -x + +if ! command_that_may_fail; then + echo "Command failed" + exit 1 +fi + +trap 'echo "Script interrupted"; exit 1' INT +``` + +## 高级 Bash 技巧 + +```bash +# 快速备份和还原 +cp file.txt{,.bak} +cp file.txt{.bak,} + +# 花括号展开 +touch file{1..5}.txt +mkdir -p project/{src,docs,tests,bin} + +# 字符串操作 +str="Hello World" +echo ${str:0:5} +echo ${str/World/Universe} +echo ${#str} + +# 数组 +array=(apple banana cherry) +echo ${array[0]} +echo ${array[@]} +echo ${#array[@]} + +# 关联数组 +declare -A assoc +assoc["name"]="John" +echo ${assoc["name"]} + +# 进程替换 +diff <(sort file1.txt) <(sort file2.txt) + +# 并行执行 +task1 & +task2 & +wait + +# xargs 并行 +find . -name "*.txt" | xargs -P 4 -I {} process {} +``` diff --git a/docs/manual/linux/STORAGE-LOGS.md b/docs/manual/linux/STORAGE-LOGS.md new file mode 100644 index 0000000..ac2e316 --- /dev/null +++ b/docs/manual/linux/STORAGE-LOGS.md @@ -0,0 +1,48 @@ +# Linux 存储与日志 + +磁盘和日志问题是线上故障中最常见的类型。排查时先判断空间、inode、目录占用和日志增长速度。 + +## 磁盘空间 + +```bash +# 查看磁盘空间 +df -h + +# 查看 inode +df -i + +# 查看目录占用 +du -sh /var/* 2>/dev/null | sort -h + +# 查找大文件 +find / -type f -size +500M 2>/dev/null +``` + +## 日志查看 + +```bash +# 查看系统日志 +journalctl -xe --no-pager + +# 查看服务日志 +journalctl -u nginx -n 100 --no-pager + +# 实时查看应用日志 +tail -f /path/to/app.log + +# 搜索错误 +grep -RniE "error|failed|exception|timeout" /var/log 2>/dev/null | head +``` + +## 删除前检查 + +```bash +pwd +ls -la /path +find /path -maxdepth 1 -print +``` + +## 延伸案例 + +- [磁盘空间满排查](../../cases/DISK-FULL.md) +- [Linux 故障应急排查清单](../../troubleshooting/LINUX-INCIDENT-CHECKLIST.md) diff --git a/docs/manual/linux/USERS-PERMISSIONS.md b/docs/manual/linux/USERS-PERMISSIONS.md new file mode 100644 index 0000000..6131f6f --- /dev/null +++ b/docs/manual/linux/USERS-PERMISSIONS.md @@ -0,0 +1,108 @@ +# Linux 用户、组与权限 + +这个专题从主手册迁移 Linux 用户管理、组管理和权限管理内容。 + +## 用户管理 + +```bash +whoami +id +su - username +sudo command +sudo su - +sudo -i + +# 创建用户 +useradd -m username +useradd -m -s /bin/bash username + +# 设置密码 +passwd username + +# 删除用户 +userdel username +userdel -r username + +# 修改用户信息 +usermod -c "Full Name" username +usermod -s /bin/zsh username + +# 查看用户 +cat /etc/passwd +who +last +``` + +## 组管理 + +```bash +groupadd groupname +groupdel groupname +usermod -aG groupname username +gpasswd -d username groupname +groups username +cat /etc/group +getent group groupname +``` + +## 权限查看 + +```bash +ls -l file.txt +``` + +权限含义: + +```text +- rw- r-- r-- +| | | | +| | | 其他用户权限 +| | 组用户权限 +| 所有者权限 +文件类型: -=文件, d=目录, l=链接 +``` + +权限值: + +- `r = 4` +- `w = 2` +- `x = 1` + +## chmod + +```bash +# 符号模式 +chmod u+x file.txt +chmod g-w file.txt +chmod o=r file.txt +chmod a+x file.txt + +# 数字模式 +chmod 755 file.txt +chmod 644 file.txt +chmod 600 file.txt +``` + +## chown/chgrp + +```bash +chown user file.txt +chown user:group file.txt +chown -R user:group dir/ +chgrp group file.txt +``` + +## 特殊权限 + +```bash +# SUID +chmod 4755 file.txt + +# SGID +chmod 2755 file.txt + +# Sticky Bit +chmod 1777 dir/ +``` + +高危提醒: `chmod -R`、`chown -R` 会递归修改目录，执行前必须确认路径边界。 diff --git a/docs/manual/middleware/DATABASE-MIDDLEWARE.md b/docs/manual/middleware/DATABASE-MIDDLEWARE.md new file mode 100644 index 0000000..41056aa --- /dev/null +++ b/docs/manual/middleware/DATABASE-MIDDLEWARE.md @@ -0,0 +1,155 @@ +# 数据库与中间件命令 + +这个页面整理常见数据库和中间件的基础排查命令，适合服务启动失败、连接失败、性能异常和日志分析场景。 + +## MySQL + +```bash +# 查看服务状态 +systemctl status mysql || systemctl status mysqld + +# 查看错误日志 +tail -n 100 /var/log/mysql/error.log 2>/dev/null +tail -n 100 /var/log/mysqld.log 2>/dev/null + +# 查看 MySQL 状态 +mysqladmin -uroot -p status + +# 连接数据库 +mysql -h 127.0.0.1 -P 3306 -uroot -p +``` + +SQL 排查: + +```sql +SHOW PROCESSLIST; +SHOW VARIABLES LIKE 'max_connections'; +SHOW STATUS LIKE 'Threads_connected'; +SHOW ENGINE INNODB STATUS\G +``` + +延伸案例: [MySQL 启动失败排查](../../cases/MYSQL-START-FAILED.md)。 + +## Redis + +```bash +# 查看服务状态 +systemctl status redis || systemctl status redis-server + +# 测试连接 +redis-cli ping +redis-cli -h 127.0.0.1 -p 6379 ping + +# 查看信息 +redis-cli info + +# 查看慢查询 +redis-cli slowlog get 10 +``` + +常用排查: + +```bash +# 查看内存 +redis-cli info memory + +# 查看客户端 +redis-cli client list + +# 查看配置 +redis-cli config get maxmemory +``` + +延伸案例: [Redis 连接失败排查](../../cases/REDIS-CONNECTION-FAILED.md)。 + +## Nginx + +```bash +# 检查配置 +nginx -t + +# 输出完整配置 +nginx -T + +# 查看服务状态 +systemctl status nginx + +# 查看错误日志 +tail -n 100 /var/log/nginx/error.log + +# 查看访问日志 +tail -n 100 /var/log/nginx/access.log +``` + +访问日志分析: + +```bash +# 统计状态码 +awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -nr + +# 查看访问最多的 IP +awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -nr | head +``` + +延伸案例: + +- [Nginx 启动失败排查](../../cases/NGINX-START-FAILED.md) +- [Nginx 502/504 排查](../../cases/NGINX-502-504.md) + +## RabbitMQ + +```bash +# 查看服务状态 +systemctl status rabbitmq-server + +# 查看节点状态 +rabbitmqctl status + +# 查看队列 +rabbitmqctl list_queues + +# 查看连接 +rabbitmqctl list_connections + +# 查看用户 +rabbitmqctl list_users +``` + +常见问题: + +- 队列堆积。 +- 连接数过多。 +- 磁盘水位触发 flow control。 +- Erlang cookie 不一致导致集群异常。 + +## Kafka + +```bash +# 查看 topic +kafka-topics.sh --bootstrap-server :9092 --list + +# 查看 topic 详情 +kafka-topics.sh --bootstrap-server :9092 --describe --topic + +# 查看消费组 +kafka-consumer-groups.sh --bootstrap-server :9092 --list + +# 查看消费组 lag +kafka-consumer-groups.sh --bootstrap-server :9092 --describe --group +``` + +常见问题: + +- 消费 lag 增长。 +- broker 磁盘满。 +- ISR 不足。 +- topic 分区和副本配置不合理。 + +## 通用排查顺序 + +1. 服务是否运行。 +2. 端口是否监听。 +3. 本机是否能连接。 +4. 应用机器是否能连接。 +5. 认证、权限、配置是否一致。 +6. 查看错误日志和慢日志。 diff --git a/docs/manual/middleware/POSTGRES-MONGO-ELASTIC.md b/docs/manual/middleware/POSTGRES-MONGO-ELASTIC.md new file mode 100644 index 0000000..2ab999c --- /dev/null +++ b/docs/manual/middleware/POSTGRES-MONGO-ELASTIC.md @@ -0,0 +1,123 @@ +# PostgreSQL、MongoDB 与 Elasticsearch + +这个页面补充常见数据库和搜索中间件的排查命令，适合连接失败、性能异常、磁盘占用、集群健康和索引问题。 + +## PostgreSQL + +```bash +# 查看服务状态 +systemctl status postgresql + +# 查看监听端口 +ss -tulnp | grep ':5432' + +# 连接数据库 +psql -h 127.0.0.1 -p 5432 -U postgres + +# 查看版本 +psql -U postgres -c "SELECT version();" +``` + +常用 SQL: + +```sql +-- 查看连接 +SELECT pid, usename, client_addr, state, query +FROM pg_stat_activity +ORDER BY query_start DESC; + +-- 查看最大连接数 +SHOW max_connections; + +-- 查看数据库大小 +SELECT datname, pg_size_pretty(pg_database_size(datname)) +FROM pg_database; + +-- 查看慢查询扩展是否可用 +SELECT * FROM pg_extension; +``` + +常见问题: + +- 连接数耗尽。 +- 认证规则 `pg_hba.conf` 不匹配。 +- 磁盘满。 +- 长事务或锁等待。 + +## MongoDB + +```bash +# 查看服务状态 +systemctl status mongod + +# 查看监听端口 +ss -tulnp | grep ':27017' + +# 连接 +mongosh + +# 查看日志 +tail -n 100 /var/log/mongodb/mongod.log +``` + +常用命令: + +```javascript +// 查看状态 +db.serverStatus() + +// 查看数据库 +show dbs + +// 查看集合 +show collections + +// 查看当前操作 +db.currentOp() + +// 查看慢查询配置 +db.getProfilingStatus() +``` + +常见问题: + +- 认证失败。 +- 副本集状态异常。 +- 磁盘空间不足。 +- 慢查询或索引缺失。 + +## Elasticsearch + +```bash +# 查看服务状态 +systemctl status elasticsearch + +# 集群健康 +curl -s http://127.0.0.1:9200/_cluster/health?pretty + +# 节点 +curl -s http://127.0.0.1:9200/_cat/nodes?v + +# 索引 +curl -s http://127.0.0.1:9200/_cat/indices?v + +# 分片 +curl -s http://127.0.0.1:9200/_cat/shards?v +``` + +常见问题: + +- 集群 yellow/red。 +- 分片未分配。 +- 磁盘水位触发只读。 +- JVM heap 使用过高。 +- 索引过多或分片过多。 + +## 通用排查顺序 + +1. 服务是否运行。 +2. 端口是否监听。 +3. 本机连接是否成功。 +4. 认证和访问控制是否正确。 +5. 磁盘、内存、连接数是否达到上限。 +6. 查看错误日志和慢查询。 diff --git a/docs/manual/observability/LOGGING-MONITORING.md b/docs/manual/observability/LOGGING-MONITORING.md new file mode 100644 index 0000000..617f229 --- /dev/null +++ b/docs/manual/observability/LOGGING-MONITORING.md @@ -0,0 +1,124 @@ +# 集中日志与监控告警 + +集中日志和监控告警的目标是快速回答三个问题: 是否采集到了、是否存储正常、是否能查询和告警。 + +## Prometheus + +```bash +# 查看服务状态 +systemctl status prometheus + +# 检查端口 +ss -tulnp | grep ':9090' + +# 查看 targets +curl -s http://127.0.0.1:9090/api/v1/targets + +# 查询 up 指标 +curl -s 'http://127.0.0.1:9090/api/v1/query?query=up' +``` + +常见问题: + +- target down。 +- scrape timeout。 +- label 配置不一致。 +- PromQL 查询为空。 + +## Node Exporter + +```bash +# 查看服务状态 +systemctl status node_exporter + +# 检查端口 +ss -tulnp | grep ':9100' + +# 查看指标 +curl -s http://127.0.0.1:9100/metrics | head +``` + +## Alertmanager + +```bash +# 查看服务状态 +systemctl status alertmanager + +# 检查端口 +ss -tulnp | grep ':9093' + +# 查看告警 +curl -s http://127.0.0.1:9093/api/v2/alerts +``` + +## Grafana + +```bash +# 查看服务状态 +systemctl status grafana-server + +# 检查端口 +ss -tulnp | grep ':3000' + +# 查看日志 +journalctl -u grafana-server -n 100 --no-pager +``` + +常见问题: + +- 数据源连接失败。 +- Dashboard 变量为空。 +- 时间范围不正确。 +- PromQL 查询错误。 + +## Loki 与 Promtail + +```bash +# Loki +systemctl status loki +ss -tulnp | grep ':3100' + +# Promtail +systemctl status promtail +journalctl -u promtail -n 100 --no-pager +``` + +排查重点: + +- Promtail 是否读取到日志文件。 +- label 是否符合查询条件。 +- Loki 是否可写入。 +- 日志时间戳是否异常。 + +## ELK/Elastic Stack + +```bash +# Elasticsearch 健康 +curl -s http://127.0.0.1:9200/_cluster/health?pretty + +# Logstash 状态 +systemctl status logstash +journalctl -u logstash -n 100 --no-pager + +# Kibana 状态 +systemctl status kibana +ss -tulnp | grep ':5601' +``` + +## 排查顺序 + +1. Agent/exporter 是否运行。 +2. 端口是否监听。 +3. 采集端是否能访问服务端。 +4. 服务端是否写入成功。 +5. 查询语句和时间范围是否正确。 +6. 告警规则是否被加载。 + +## 常见现象 + +| 现象 | 优先排查 | +| --- | --- | +| 监控没有数据 | exporter、Prometheus targets、网络 | +| 告警不触发 | PromQL、规则加载、Alertmanager | +| 日志查不到 | agent、路径、label、时间范围 | +| Dashboard 空白 | 数据源、变量、时间范围 | diff --git a/docs/manual/observability/PROMQL-LOGQL-ALERTS.md b/docs/manual/observability/PROMQL-LOGQL-ALERTS.md new file mode 100644 index 0000000..5813123 --- /dev/null +++ b/docs/manual/observability/PROMQL-LOGQL-ALERTS.md @@ -0,0 +1,117 @@ +# PromQL、LogQL 与告警规则 + +监控告警不只是部署 Prometheus 和 Grafana，还需要能写查询、定位指标、配置告警规则，并理解告警为什么触发或没有触发。 + +## PromQL 基础 + +```promql +# 服务是否在线 +up + +# 指定 job +up{job="node"} + +# CPU 使用率示例 +100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) + +# 内存可用率 +node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes * 100 + +# 磁盘使用率 +100 - (node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes{fstype!~"tmpfs|overlay"} * 100) +``` + +## PromQL 排查技巧 + +```promql +# 查看某个指标有哪些标签 +count by(__name__) ({__name__=~"node_.*"}) + +# 查看 scrape 是否成功 +up == 0 + +# 过去 5 分钟请求速率 +rate(http_requests_total[5m]) + +# 95 分位延迟 +histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le)) +``` + +## LogQL 基础 + +```logql +# 查询 app 标签 +{app="nginx"} + +# 包含 error +{app="nginx"} |= "error" + +# 正则匹配 +{app="nginx"} |~ "error|timeout|failed" + +# JSON 解析 +{app="api"} | json | status >= 500 +``` + +## LogQL 统计 + +```logql +# 5 分钟错误日志数量 +count_over_time({app="api"} |= "error" [5m]) + +# 按状态码统计 +sum by(status) (count_over_time({app="nginx"} | json [5m])) +``` + +## Prometheus 告警规则示例 + +```yaml +groups: + - name: node-alerts + rules: + - alert: InstanceDown + expr: up == 0 + for: 2m + labels: + severity: critical + annotations: + summary: "Instance down" + description: "{{ $labels.instance }} has been down for more than 2 minutes." + + - alert: DiskUsageHigh + expr: 100 - (node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes{fstype!~"tmpfs|overlay"} * 100) > 85 + for: 5m + labels: + severity: warning + annotations: + summary: "Disk usage high" + description: "{{ $labels.instance }} disk usage is above 85%." +``` + +## 告警不触发排查 + +```bash +# 查看 Prometheus 规则 +curl -s http://127.0.0.1:9090/api/v1/rules + +# 查看告警 +curl -s http://127.0.0.1:9090/api/v1/alerts + +# 查看 Alertmanager 告警 +curl -s http://127.0.0.1:9093/api/v2/alerts +``` + +排查重点: + +- PromQL 是否有数据。 +- `for` 时间是否还没满足。 +- label 是否匹配路由规则。 +- Alertmanager 是否收到告警。 +- silence 是否屏蔽告警。 + +## 告警规则建议 + +- 告警表达式要能直接指向影响。 +- 避免过度敏感导致告警风暴。 +- 为每条告警写清楚 summary 和 description。 +- 告警标签至少包含 severity、service、instance。 diff --git a/docs/manual/powershell/ADVANCED-SCRIPTING.md b/docs/manual/powershell/ADVANCED-SCRIPTING.md new file mode 100644 index 0000000..d26a044 --- /dev/null +++ b/docs/manual/powershell/ADVANCED-SCRIPTING.md @@ -0,0 +1,119 @@ +# PowerShell 高级技巧 + +这个专题从主手册迁移 PowerShell 管道、对象、变量、脚本控制流和错误处理内容。 + +## 管道与对象操作 + +```powershell +# 选择特定属性 +Get-Process | Select-Object Name, ID, WorkingSet + +# 过滤对象 +Get-Process | Where-Object { $_.WorkingSet -gt 100MB } + +# 排序 +Get-Process | Sort-Object WorkingSet -Descending + +# 分组 +Get-Process | Group-Object -Property PriorityClass + +# 测量 +Get-ChildItem | Measure-Object -Property Length -Sum -Average -Maximum -Minimum +``` + +复杂管道示例: + +```powershell +Get-WmiObject Win32_Service | + Where-Object { $_.State -eq "Running" } | + Group-Object -Property StartMode | + Select-Object Name, Count | + Sort-Object Count -Descending +``` + +## 变量与集合 + +```powershell +$name = "PowerShell" +$number = 42 +$array = 1, 2, 3, 4, 5 +$hash = @{ Key1 = "Value1"; Key2 = "Value2" } + +# 数组 +$array[0] +$array[-1] +$array[1..3] + +# 哈希表 +$hash["Key1"] +$hash.NewKey = "NewValue" +``` + +## 控制流 + +```powershell +if ($number -gt 40) { + Write-Host "Number is greater than 40" +} elseif ($number -eq 40) { + Write-Host "Number is exactly 40" +} else { + Write-Host "Number is less than 40" +} + +switch ($number) { + 42 { Write-Host "The answer!" } + { $_ -gt 40 } { Write-Host "Greater than 40" } + default { Write-Host "Something else" } +} +``` + +## 循环 + +```powershell +for ($i = 0; $i -lt 5; $i++) { + Write-Host "Iteration $i" +} + +foreach ($item in $array) { + Write-Host "Item: $item" +} + +$array | ForEach-Object { Write-Host "Item: $_" } + +$i = 0 +while ($i -lt 5) { + Write-Host "Iteration $i" + $i++ +} +``` + +## 函数 + +```powershell +function Get-Hello { + param([string]$Name = "World") + Write-Host "Hello, $Name!" +} + +Get-Hello -Name "PowerShell" +``` + +## 错误处理 + +```powershell +try { + Get-Content -Path "nonexistent.txt" -ErrorAction Stop +} catch [System.Management.Automation.ItemNotFoundException] { + Write-Host "File not found: $_" +} catch { + Write-Host "An error occurred: $_" +} finally { + Write-Host "This always runs" +} + +if (Get-Command -Name "NonExistentCommand" -ErrorAction SilentlyContinue) { + Write-Host "Command exists" +} else { + Write-Host "Command does not exist" +} +``` diff --git a/docs/manual/powershell/BASIC.md b/docs/manual/powershell/BASIC.md new file mode 100644 index 0000000..dab201b --- /dev/null +++ b/docs/manual/powershell/BASIC.md @@ -0,0 +1,80 @@ +# PowerShell 基础命令 + +这个页面整理 PowerShell 日常使用最频繁的文件、目录、文本查看和搜索命令。更完整的原始内容可查看根目录主手册。 + +## 目录导航 + +```powershell +# 查看当前路径 +Get-Location + +# 切换目录 +Set-Location C:\Users + +# 返回上级目录 +Set-Location .. + +# 切换到用户主目录 +Set-Location ~ +``` + +## 文件与目录 + +```powershell +# 列出当前目录内容 +Get-ChildItem + +# 列出隐藏文件 +Get-ChildItem -Force + +# 递归列出文件 +Get-ChildItem -Recurse + +# 创建目录 +New-Item -ItemType Directory demo + +# 创建文件 +New-Item notes.txt +``` + +## 读取与搜索 + +```powershell +# 查看文件内容 +Get-Content .\app.log + +# 查看前 20 行 +Get-Content .\app.log -TotalCount 20 + +# 查看后 100 行 +Get-Content .\app.log -Tail 100 + +# 实时查看日志 +Get-Content .\app.log -Tail 100 -Wait + +# 搜索关键字 +Select-String -Path .\*.log -Pattern "error" +``` + +## 复制、移动和删除 + +```powershell +# 复制文件 +Copy-Item source.txt dest.txt + +# 复制目录 +Copy-Item source_dir dest_dir -Recurse + +# 移动或重命名 +Move-Item old.txt new.txt + +# 删除文件 +Remove-Item file.txt + +# 删除目录前预览 +Remove-Item C:\Temp\old -Recurse -Force -WhatIf +``` + +## 安全提醒 + +`Remove-Item -Recurse -Force` 属于高危删除命令。生产环境执行前建议先使用 `-WhatIf` 预览，确认路径无误后再执行。 diff --git a/docs/manual/powershell/SYSTEM-ADMIN.md b/docs/manual/powershell/SYSTEM-ADMIN.md new file mode 100644 index 0000000..4ee55f2 --- /dev/null +++ b/docs/manual/powershell/SYSTEM-ADMIN.md @@ -0,0 +1,72 @@ +# PowerShell 系统管理 + +PowerShell 适合做 Windows 系统信息采集、进程排查、服务管理和网络诊断。 + +## 系统信息 + +```powershell +# 查看系统信息 +Get-ComputerInfo + +# 查看计算机名称 +$env:COMPUTERNAME + +# 查看磁盘 +Get-PSDrive -PSProvider FileSystem +``` + +## 进程管理 + +```powershell +# 查看进程 +Get-Process + +# 按 CPU 排序 +Get-Process | Sort-Object CPU -Descending | Select-Object -First 10 Name, Id, CPU + +# 按内存排序 +Get-Process | Sort-Object WorkingSet -Descending | Select-Object -First 10 Name, Id, WorkingSet + +# 停止进程 +Stop-Process -Id +``` + +## 服务管理 + +```powershell +# 查看服务 +Get-Service + +# 查看指定服务 +Get-Service -Name "Spooler" + +# 启动服务 +Start-Service -Name "Spooler" + +# 停止服务 +Stop-Service -Name "Spooler" + +# 重启服务 +Restart-Service -Name "Spooler" +``` + +## 网络诊断 + +```powershell +# Ping 测试 +Test-Connection example.com + +# 测试端口 +Test-NetConnection example.com -Port 443 + +# 查看 TCP 连接 +Get-NetTCPConnection + +# 查看监听端口 +Get-NetTCPConnection -State Listen +``` + +## 延伸阅读 + +- [PowerShell 实用场景](../../powershell/POWERSHELL-PRACTICAL.md) +- [PowerShell 与 Bash 命令对照](../../POWERSHELL-BASH-COMPARISON.md) diff --git a/docs/manual/security/FIREWALL-SELINUX.md b/docs/manual/security/FIREWALL-SELINUX.md new file mode 100644 index 0000000..93113f1 --- /dev/null +++ b/docs/manual/security/FIREWALL-SELINUX.md @@ -0,0 +1,105 @@ +# 防火墙与 SELinux + +防火墙和 SELinux 属于高风险变更。远程服务器操作前应保留当前 SSH 会话，并准备回滚命令。 + +## firewalld + +```bash +# 查看状态 +firewall-cmd --state + +# 查看当前 zone +firewall-cmd --get-active-zones + +# 查看规则 +firewall-cmd --list-all + +# 临时开放端口 +sudo firewall-cmd --add-port=8080/tcp + +# 永久开放端口 +sudo firewall-cmd --permanent --add-port=8080/tcp +sudo firewall-cmd --reload + +# 删除端口 +sudo firewall-cmd --permanent --remove-port=8080/tcp +sudo firewall-cmd --reload +``` + +## ufw + +```bash +# 查看状态 +sudo ufw status verbose + +# 允许 SSH +sudo ufw allow 22/tcp + +# 允许 HTTP/HTTPS +sudo ufw allow 80/tcp +sudo ufw allow 443/tcp + +# 拒绝端口 +sudo ufw deny 8080/tcp +``` + +## iptables + +```bash +# 查看规则 +sudo iptables -L -n -v + +# 备份规则 +sudo iptables-save > iptables.backup + +# 允许端口 +sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT +``` + +高危提醒: `iptables -F` 会清空规则，可能导致服务暴露或远程连接中断。 + +## nftables + +```bash +# 查看规则 +sudo nft list ruleset + +# 查看表 +sudo nft list tables +``` + +## SELinux + +```bash +# 查看状态 +getenforce +sestatus + +# 临时切换为 Permissive +sudo setenforce 0 + +# 临时切换为 Enforcing +sudo setenforce 1 +``` + +查看 SELinux 拒绝记录: + +```bash +sudo ausearch -m avc -ts recent +sudo journalctl | grep -i selinux +``` + +## 排查顺序 + +1. 先确认服务是否监听: `ss -tulnp`。 +2. 再确认本机访问是否正常: `curl 127.0.0.1:`。 +3. 再确认防火墙规则。 +4. 最后检查 SELinux 或安全中心策略。 + +## 高危提醒 + +- 不要为了排障长期关闭防火墙或 SELinux。 +- 修改远程服务器防火墙前保留当前 SSH 会话。 +- 生产环境建议先添加允许规则，再删除旧规则。 + +延伸阅读: [命令风险等级说明](../../security/RISK-LEVELS.md)。 diff --git a/docs/manual/security/HARDENING.md b/docs/manual/security/HARDENING.md new file mode 100644 index 0000000..f03233e --- /dev/null +++ b/docs/manual/security/HARDENING.md @@ -0,0 +1,73 @@ +# 系统安全加固 + +安全加固应按“账号、权限、服务、网络、日志、审计”的顺序推进。生产环境修改前建议先备份配置，并准备回滚方案。 + +## 账号与权限 + +```bash +# 查看当前用户 +whoami + +# 查看用户和组 +id + +# 查看登录记录 +last -n 20 + +# 查看 sudo 配置 +sudo -l +``` + +建议: + +- 最小权限原则。 +- 管理员操作保留审计记录。 +- 不共享 root 密码。 +- 不长期使用 `chmod 777`。 + +## SSH 加固 + +```bash +# 检查 SSH 配置语法 +sshd -t + +# 查看 SSH 服务状态 +systemctl status sshd || systemctl status ssh + +# 查看 SSH 日志 +journalctl -u sshd -n 100 --no-pager +``` + +建议: + +- 禁止弱密码。 +- 使用密钥登录。 +- 修改配置前保留当前登录会话。 + +## 防火墙 + +```bash +# firewalld +firewall-cmd --list-all + +# iptables 备份 +iptables-save > iptables.backup + +# ufw +ufw status verbose +``` + +## 日志与审计 + +```bash +# 查看系统日志 +journalctl -xe --no-pager + +# 查看认证日志 +grep -i "failed" /var/log/auth.log 2>/dev/null +``` + +## 延伸阅读 + +- [命令风险等级说明](../../security/RISK-LEVELS.md) +- [SSH 连接失败排查](../../cases/SSH-CONNECTION-FAILED.md) diff --git a/docs/manual/security/LOGGING-AUDIT.md b/docs/manual/security/LOGGING-AUDIT.md new file mode 100644 index 0000000..ae2ec54 --- /dev/null +++ b/docs/manual/security/LOGGING-AUDIT.md @@ -0,0 +1,255 @@ +# 日志轮转、审计与系统日志 + +日志系统排查要关注三件事: 日志是否写入、是否轮转、是否能保留足够的审计证据。 + +## journalctl + +```bash +# 查看最近系统日志 +journalctl -xe --no-pager + +# 查看指定服务日志 +journalctl -u nginx -n 100 --no-pager + +# 按时间查看 +journalctl --since "1 hour ago" + +# 实时查看 +journalctl -f +``` + +### journald 持久化 + +```bash +# 编辑配置 +sudo vi /etc/systemd/journald.conf +``` + +示例: + +```ini +[Journal] +Storage=persistent +Compress=yes +Seal=yes +SystemMaxUse=10G +SystemKeepFree=5G +SystemMaxFileSize=100M +MaxRetentionSec=1month +ForwardToSyslog=yes +``` + +应用配置: + +```bash +sudo systemctl restart systemd-journald +systemctl status systemd-journald +journalctl --disk-usage +``` + +常用高级查询: + +```bash +# 多服务查询 +journalctl -u nginx -u mysql + +# 按优先级查询 +journalctl -p err..alert + +# 按时间窗口查询 +journalctl --since today +journalctl --since "2026-03-13 09:00:00" --until "2026-03-13 17:00:00" +journalctl --since "-2h" + +# JSON 输出 +journalctl -u nginx -o json +journalctl -u nginx -o json-pretty + +# 清理旧日志 +journalctl --vacuum-time=1month +journalctl --vacuum-size=5G +``` + +## logrotate + +```bash +# 查看 logrotate 主配置 +cat /etc/logrotate.conf + +# 查看应用配置 +ls /etc/logrotate.d/ + +# 调试指定配置 +sudo logrotate -d /etc/logrotate.conf + +# 强制轮转 +sudo logrotate -f /etc/logrotate.conf +``` + +示例: + +```text +/var/log/app/*.log { + daily + rotate 14 + compress + missingok + notifempty + copytruncate +} +``` + +生产配置示例: + +```text +/var/log/custom/*.log { + daily + rotate 30 + compress + delaycompress + missingok + notifempty + create 0640 root adm + sharedscripts + postrotate + systemctl reload rsyslog > /dev/null 2>&1 || true + endscript +} +``` + +注意: + +- `copytruncate` 适合无法重启或 reload 的应用，但可能丢少量日志。 +- 更推荐应用支持 reopen log 或配合服务 reload。 + +## rsyslog + +```bash +# 查看服务状态 +systemctl status rsyslog + +# 查看配置 +cat /etc/rsyslog.conf +ls /etc/rsyslog.d/ + +# 测试写入日志 +logger "test rsyslog message" + +# 查看系统日志 +tail -n 50 /var/log/messages 2>/dev/null +tail -n 50 /var/log/syslog 2>/dev/null +``` + +### rsyslog 集中日志 + +```bash +# 主配置文件 +sudo vi /etc/rsyslog.conf + +# 自定义配置 +sudo vi /etc/rsyslog.d/50-custom.conf +``` + +模板示例: + +```text +$template HighPrecisionFormat,"%timestamp:::date-rfc3339% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n" +$template JsonFormat,"{\"timestamp\":\"%timestamp:::date-rfc3339%\",\"host\":\"%HOSTNAME%\",\"tag\":\"%syslogtag%\",\"msg\":\"%msg:::json%\"}\n" +$template PerHostLog,"/var/log/remote/%HOSTNAME%/%PROGRAMNAME%.log" +``` + +远程接收和转发: + +```text +# UDP 接收 +module(load="imudp") +input(type="imudp" port="514") + +# TCP 接收 +module(load="imtcp") +input(type="imtcp" port="514") + +# TCP 转发 +*.* @@logserver.example.com:514 + +# UDP 转发 +*.* @logserver.example.com:514 + +# 按程序名过滤 +if $programname == 'sshd' then /var/log/sshd.log +& stop + +# 同时写入本地和远程 +*.* /var/log/all.log +*.* @@logserver.example.com:514 +``` + +TLS 传输需要证书、CA 和服务端配置匹配，建议先在测试环境验证: + +```text +module(load="imtcp" StreamDriver.Name="gtls" StreamDriver.Mode="1" StreamDriver.AuthMode="x509/name" PermittedPeer="*.example.com") +global(DefaultNetstreamDriver="gtls" DefaultNetstreamDriverCAFile="/etc/pki/rsyslog/ca.pem" DefaultNetstreamDriverCertFile="/etc/pki/rsyslog/server-cert.pem" DefaultNetstreamDriverKeyFile="/etc/pki/rsyslog/server-key.pem") +``` + +## auditd + +```bash +# 查看服务状态 +systemctl status auditd + +# 查看规则 +auditctl -l + +# 搜索 sudo 执行 +ausearch -x sudo + +# 搜索最近拒绝 +ausearch -m avc -ts recent + +# 生成报告 +aureport +``` + +示例规则: + +```bash +# 监控 sudoers 修改 +-w /etc/sudoers -p wa -k sudoers_changes + +# 监控 passwd 修改 +-w /etc/passwd -p wa -k passwd_changes +``` + +## 生产变更前检查 + +```bash +# 检查磁盘空间 +df -h +du -sh /var/log/* 2>/dev/null + +# 检查服务状态 +systemctl status rsyslog +systemctl status systemd-journald +systemctl status auditd + +# 备份配置 +sudo cp /etc/rsyslog.conf /etc/rsyslog.conf.bak +sudo cp /etc/systemd/journald.conf /etc/systemd/journald.conf.bak +``` + +## 常见问题 + +| 问题 | 排查 | +| --- | --- | +| 日志文件过大 | `du -sh /var/log/*`、`logrotate -d` | +| journal 占用大 | `journalctl --disk-usage` | +| 日志没有写入 | 服务状态、权限、配置路径 | +| 审计规则不生效 | `auditctl -l`、`systemctl status auditd` | + +## 高危提醒 + +- 不要直接删除正在写入的日志文件，可能导致空间不释放。 +- 删除日志前确认是否需要保留排障和审计证据。 +- 审计规则过多可能影响性能，需要按关键路径配置。 +- 修改集中日志转发前，先确认网络、防火墙、证书和接收端容量。 +- 清理日志优先使用 `journalctl --vacuum-*`、logrotate 或服务 reload，不要直接 `rm -f` 正在写入的文件。 diff --git a/docs/manual/security/SUDOERS-APPARMOR.md b/docs/manual/security/SUDOERS-APPARMOR.md new file mode 100644 index 0000000..550c0d3 --- /dev/null +++ b/docs/manual/security/SUDOERS-APPARMOR.md @@ -0,0 +1,83 @@ +# sudoers 与 AppArmor + +权限问题不要一上来使用 `chmod 777`。更好的方式是确认用户、组、sudo 权限、安全策略和应用访问路径。 + +## sudo 权限查看 + +```bash +# 查看当前用户 +whoami +id + +# 查看当前用户 sudo 权限 +sudo -l + +# 查看用户所属组 +groups +``` + +## 编辑 sudoers + +风险等级: 高 + +```bash +# 安全编辑 sudoers +sudo visudo + +# 编辑扩展配置 +sudo visudo -f /etc/sudoers.d/ +``` + +示例: + +```text +# 允许 deploy 用户免密重启 nginx +deploy ALL=(root) NOPASSWD: /bin/systemctl restart nginx +``` + +建议: + +- 使用 `visudo`，不要直接用普通编辑器改 `/etc/sudoers`。 +- 命令授权尽量精确到具体命令。 +- 不建议随意配置 `NOPASSWD: ALL`。 + +## AppArmor 状态 + +```bash +# 查看状态 +sudo aa-status + +# 查看 profile +ls /etc/apparmor.d/ + +# 投诉模式 +sudo aa-complain + +# 强制模式 +sudo aa-enforce +``` + +## AppArmor 日志 + +```bash +# 查看内核日志 +dmesg | grep -i apparmor + +# 查看系统日志 +journalctl | grep -i apparmor +``` + +## 常见问题 + +| 现象 | 排查 | +| --- | --- | +| sudo 提示无权限 | `sudo -l`、用户组、sudoers | +| 修改 sudoers 后 sudo 不可用 | 使用恢复会话修复语法 | +| 应用无法读取文件 | AppArmor/SELinux、安全中心、文件权限 | +| 容器访问挂载目录失败 | 文件权限、AppArmor profile、SELinux label | + +## 高危提醒 + +- sudoers 语法错误可能导致管理员无法使用 sudo。 +- 修改 sudoers 前保留 root 会话或准备恢复方式。 +- 不要长期把安全策略切到宽松模式，只用于临时定位问题。 diff --git a/docs/manual/windows/ADMIN-COMMANDS.md b/docs/manual/windows/ADMIN-COMMANDS.md new file mode 100644 index 0000000..041ce2c --- /dev/null +++ b/docs/manual/windows/ADMIN-COMMANDS.md @@ -0,0 +1,101 @@ +# Windows 管理命令 + +这个页面整理 Windows 运维中常用的 PowerShell 管理命令，覆盖事件日志、注册表、计划任务、防火墙和远程管理。 + +## 事件日志 + +```powershell +# 查看系统日志 +Get-WinEvent -LogName System -MaxEvents 20 + +# 查看应用日志 +Get-WinEvent -LogName Application -MaxEvents 20 + +# 按级别筛选错误 +Get-WinEvent -FilterHashtable @{LogName="System"; Level=2} -MaxEvents 20 + +# 传统事件日志命令 +Get-EventLog -LogName System -Newest 20 +``` + +## 注册表 + +```powershell +# 读取注册表 +Get-ItemProperty "HKLM:\Software\Microsoft\Windows\CurrentVersion" + +# 创建键 +New-Item -Path "HKCU:\Software\Demo" -Force + +# 设置值 +Set-ItemProperty -Path "HKCU:\Software\Demo" -Name "Enabled" -Value 1 + +# 删除值 +Remove-ItemProperty -Path "HKCU:\Software\Demo" -Name "Enabled" +``` + +风险提醒: 修改注册表可能影响系统或应用行为，执行前建议导出备份。 + +## 计划任务 + +```powershell +# 查看计划任务 +Get-ScheduledTask + +# 查看指定任务 +Get-ScheduledTask -TaskName "" + +# 启动任务 +Start-ScheduledTask -TaskName "" + +# 停止任务 +Stop-ScheduledTask -TaskName "" +``` + +## Windows 防火墙 + +```powershell +# 查看防火墙规则 +Get-NetFirewallRule + +# 查看启用的入站规则 +Get-NetFirewallRule -Direction Inbound -Enabled True + +# 新增允许端口规则 +New-NetFirewallRule -DisplayName "Allow 8080" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow + +# 禁用规则 +Disable-NetFirewallRule -DisplayName "Allow 8080" +``` + +## 远程管理 + +```powershell +# 进入远程会话 +Enter-PSSession -ComputerName + +# 远程执行命令 +Invoke-Command -ComputerName -ScriptBlock { hostname } + +# 测试 WinRM +Test-WSMan +``` + +## 软件包与模块 + +```powershell +# winget 搜索和安装 +winget search +winget install + +# PowerShell 模块 +Find-Module +Install-Module -Scope CurrentUser +``` + +## 排查建议 + +- 先用 `Get-WinEvent` 查系统和应用日志。 +- 服务类问题结合 `Get-Service`、`Get-Process`。 +- 网络类问题结合 `Test-NetConnection` 和 `Get-NetTCPConnection`。 +- 远程管理失败时检查 WinRM、防火墙、账号权限和网络连通。 diff --git a/docs/powershell/POWERSHELL-PRACTICAL.md b/docs/powershell/POWERSHELL-PRACTICAL.md new file mode 100644 index 0000000..cd768a4 --- /dev/null +++ b/docs/powershell/POWERSHELL-PRACTICAL.md @@ -0,0 +1,68 @@ +# PowerShell 实用场景 + +PowerShell 的核心优势是对象管道。日常运维中，尽量使用结构化对象筛选，而不是把输出当普通文本处理。 + +## 进程排查 + +```powershell +# 按 CPU 排序 +Get-Process | Sort-Object CPU -Descending | Select-Object -First 10 Name, Id, CPU + +# 按内存排序 +Get-Process | Sort-Object WorkingSet -Descending | Select-Object -First 10 Name, Id, WorkingSet + +# 查找指定进程 +Get-Process -Name "nginx" -ErrorAction SilentlyContinue +``` + +## 文件搜索 + +```powershell +# 查找日志文件 +Get-ChildItem -Path C:\Logs -Recurse -Filter "*.log" + +# 搜索错误关键字 +Select-String -Path C:\Logs\*.log -Pattern "error" + +# 查找大文件 +Get-ChildItem C:\ -Recurse -ErrorAction SilentlyContinue | + Where-Object Length -gt 500MB | + Sort-Object Length -Descending | + Select-Object -First 20 FullName, Length +``` + +## 服务管理 + +```powershell +# 查看服务 +Get-Service + +# 查看指定服务 +Get-Service -Name "Spooler" + +# 重启服务 +Restart-Service -Name "Spooler" +``` + +## 删除前预览 + +```powershell +# 预览将要删除的内容 +Remove-Item C:\Temp\old -Recurse -Force -WhatIf + +# 确认无误后再执行 +Remove-Item C:\Temp\old -Recurse -Force +``` + +## 网络排查 + +```powershell +# Ping 测试 +Test-Connection example.com + +# 测试端口 +Test-NetConnection example.com -Port 443 + +# 查看监听端口 +Get-NetTCPConnection -State Listen +``` diff --git a/docs/schema/health-check-report.schema.json b/docs/schema/health-check-report.schema.json new file mode 100644 index 0000000..f09dbd8 --- /dev/null +++ b/docs/schema/health-check-report.schema.json @@ -0,0 +1,210 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://shiwenxin123.github.io/PowerShell-Linux-/schema/health-check-report.schema.json", + "title": "Health Check Report", + "type": "object", + "required": [ + "metadata", + "modules", + "summary", + "errors" + ], + "additionalProperties": false, + "properties": { + "metadata": { + "type": "object", + "required": [ + "os", + "hostname", + "timestamp", + "module", + "format", + "script" + ], + "additionalProperties": false, + "properties": { + "os": { + "type": "string", + "minLength": 1 + }, + "hostname": { + "type": "string", + "minLength": 1 + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "module": { + "type": "string", + "enum": [ + "all", + "system", + "disk", + "network", + "service", + "process" + ] + }, + "format": { + "type": "string", + "const": "json" + }, + "script": { + "type": "string", + "enum": [ + "linux-health-check.sh", + "windows-health-check.ps1" + ] + } + } + }, + "modules": { + "type": "object", + "required": [ + "system", + "disk", + "network", + "service", + "process" + ], + "additionalProperties": false, + "properties": { + "system": { + "$ref": "#/$defs/moduleResult" + }, + "disk": { + "$ref": "#/$defs/moduleResult" + }, + "network": { + "$ref": "#/$defs/moduleResult" + }, + "service": { + "$ref": "#/$defs/moduleResult" + }, + "process": { + "$ref": "#/$defs/moduleResult" + } + } + }, + "summary": { + "type": "object", + "required": [ + "status", + "warnings_count", + "errors_count" + ], + "additionalProperties": false, + "properties": { + "status": { + "type": "string", + "enum": [ + "ok", + "warning", + "error" + ] + }, + "warnings_count": { + "type": "integer", + "minimum": 0 + }, + "errors_count": { + "type": "integer", + "minimum": 0 + } + } + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/$defs/message" + } + } + }, + "$defs": { + "moduleResult": { + "type": "object", + "required": [ + "status", + "commands", + "warnings", + "errors" + ], + "additionalProperties": false, + "properties": { + "status": { + "type": "string", + "enum": [ + "ok", + "warning", + "error", + "skipped" + ] + }, + "commands": { + "type": "array", + "items": { + "$ref": "#/$defs/commandResult" + } + }, + "warnings": { + "type": "array", + "items": { + "$ref": "#/$defs/message" + } + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/$defs/message" + } + } + } + }, + "commandResult": { + "type": "object", + "required": [ + "name", + "command", + "exit_code", + "output" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "command": { + "type": "string", + "minLength": 1 + }, + "exit_code": { + "type": "integer", + "minimum": 0 + }, + "output": { + "type": "string" + } + } + }, + "message": { + "type": "object", + "required": [ + "name", + "message" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string", + "minLength": 1 + } + } + } + } +} diff --git a/docs/security/RISK-LEVELS.md b/docs/security/RISK-LEVELS.md new file mode 100644 index 0000000..e9ed85f --- /dev/null +++ b/docs/security/RISK-LEVELS.md @@ -0,0 +1,186 @@ +# 命令风险等级说明 + +命令手册中涉及系统配置、权限、删除和磁盘操作。为了降低误操作风险，建议后续新增命令时统一标注风险等级。 + +## 风险等级 + +| 等级 | 含义 | 示例 | +| --- | --- | --- | +| 低 | 只读查询，不改变系统状态 | `ls`、`Get-Process`、`df -h` | +| 中 | 修改普通文件、启动停止服务、安装软件 | `systemctl restart`、`apt install` | +| 高 | 可能导致数据丢失、权限失控、网络中断 | `rm -rf`、`chmod -R 777`、`mkfs` | + +## 高危命令清单 + +| 命令 | 风险 | 更安全的做法 | +| --- | --- | --- | +| `rm -rf /path` | 递归强制删除，删除后通常不可恢复 | 先执行 `ls /path` 或 `find /path -maxdepth 1` | +| `Remove-Item -Recurse -Force` | Windows 递归强制删除 | 先加 `-WhatIf` 预览 | +| `chmod -R 777` | 过度开放权限 | 使用最小权限，例如 `chmod 750` | +| `chown -R user:group /path` | 批量修改属主，可能影响服务运行 | 先确认目录边界 | +| `mkfs.* /dev/sdX` | 格式化磁盘，清空文件系统 | 先执行 `lsblk` 确认设备 | +| `dd if=... of=...` | 低级磁盘写入，目标写错会破坏数据 | 反复确认 `of` 目标 | +| `iptables -F` | 清空防火墙规则，可能暴露服务 | 先备份规则 | +| `systemctl stop sshd` | 可能断开远程管理入口 | 保留现有 SSH 会话 | + +## 按场景标注规范 + +### 删除类 + +风险等级: 高 + +典型命令: + +```bash +rm -rf /path +find /path -type f -delete +``` + +```powershell +Remove-Item C:\Path -Recurse -Force +``` + +执行前检查: + +```bash +pwd +ls -la /path +find /path -maxdepth 1 -print +``` + +```powershell +Get-Location +Get-ChildItem C:\Path +Remove-Item C:\Path -Recurse -Force -WhatIf +``` + +### 权限类 + +风险等级: 中到高 + +典型命令: + +```bash +chmod -R 777 /path +chown -R user:group /path +``` + +执行前检查: + +```bash +ls -ld /path +find /path -maxdepth 2 -ls | head +``` + +建议: + +- 避免 `777`，优先使用最小权限。 +- 修改目录前确认服务运行用户。 +- 批量修改前先在单个文件或测试目录验证。 + +### 磁盘类 + +风险等级: 高 + +典型命令: + +```bash +mkfs.ext4 /dev/sdX +dd if=image.iso of=/dev/sdX bs=4M +parted /dev/sdX +``` + +执行前检查: + +```bash +lsblk +blkid +mount | grep /dev/sdX +``` + +建议: + +- 反复确认设备名。 +- 确认是否有备份。 +- 不在业务运行时直接操作挂载中的数据盘。 + +### 网络与防火墙类 + +风险等级: 中到高 + +典型命令: + +```bash +iptables -F +firewall-cmd --reload +ufw deny 22 +``` + +执行前检查: + +```bash +iptables-save > iptables.backup +firewall-cmd --list-all +ss -tulnp +``` + +建议: + +- 远程服务器修改防火墙前保留当前 SSH 会话。 +- 先增加允许规则，再删除旧规则。 +- 使用定时回滚任务降低误操作风险。 + +### 服务类 + +风险等级: 中 + +典型命令: + +```bash +systemctl restart nginx +systemctl stop sshd +``` + +```powershell +Restart-Service nginx +Stop-Service sshd +``` + +执行前检查: + +```bash +systemctl status +journalctl -u -n 50 --no-pager +``` + +建议: + +- 重启前确认是否有主备、负载均衡或维护窗口。 +- SSH、数据库、网关等基础服务要特别谨慎。 + +## 推荐模板 + +````markdown +### 命令场景 + +风险等级: 低 / 中 / 高 + +```bash +# 命令说明 +command --option value +``` + +注意事项: + +- 适用系统: +- 版本限制: +- 执行前检查: + +```` + +## 写作文档时的安全原则 + +- 高危命令必须给出执行前检查命令。 +- 不把破坏性命令放在章节第一条。 +- 不用真实密码、Token、内网地址作为示例。 +- 涉及生产环境的命令尽量写明回滚方式。 diff --git a/docs/troubleshooting/COMMON-ERRORS.md b/docs/troubleshooting/COMMON-ERRORS.md new file mode 100644 index 0000000..fb98d79 --- /dev/null +++ b/docs/troubleshooting/COMMON-ERRORS.md @@ -0,0 +1,148 @@ +# 常见报错排查 + +这个页面收集日常命令行和运维中最常见的错误。每个问题都尽量给出“先查什么、再怎么处理”的路径。 + +## Permission denied + +常见原因: + +- 当前用户没有文件或目录权限。 +- 文件没有执行权限。 +- 目录缺少进入权限。 +- SELinux、AppArmor 或安全中心策略限制。 + +排查命令: + +```bash +whoami +id +ls -l /path/to/file +ls -ld /path/to/dir +``` + +处理建议: + +```bash +# 给脚本增加执行权限 +chmod +x script.sh + +# 使用 sudo 执行需要管理员权限的命令 +sudo command +``` + +不要一上来就执行 `chmod -R 777`。这会扩大权限风险。 + +## command not found + +常见原因: + +- 命令没有安装。 +- 命令所在目录不在 `PATH`。 +- 使用了错误的软件包名。 + +排查命令: + +```bash +which command +command -v command +echo "$PATH" +``` + +处理建议: + +```bash +# Debian/Ubuntu/UOS 兼容环境 +sudo apt update +sudo apt install + +# RPM/YUM 兼容环境 +sudo yum install +``` + +## Address already in use + +常见原因: + +- 端口已经被其他进程占用。 +- 服务重复启动。 +- 上一次进程没有退出。 + +排查命令: + +```bash +ss -tulnp | grep ':8080' +lsof -i :8080 +``` + +Windows PowerShell: + +```powershell +Get-NetTCPConnection -LocalPort 8080 +``` + +处理建议: + +- 确认占用端口的进程是否属于当前服务。 +- 优先使用服务管理命令停止，不确定时不要直接强杀。 + +## No space left on device + +常见原因: + +- 磁盘空间满。 +- inode 用完。 +- 日志或临时文件暴涨。 + +排查命令: + +```bash +df -h +df -i +du -sh /* 2>/dev/null +find / -type f -size +500M 2>/dev/null +``` + +处理建议: + +- 优先清理可确认的临时文件、旧日志、旧备份。 +- 删除日志前先确认是否需要保留排障证据。 +- 删除文件后空间未释放时，检查是否有进程仍占用已删除文件。 + +```bash +lsof | grep deleted +``` + +## Network is unreachable + +常见原因: + +- 网卡未配置 IP。 +- 默认路由缺失。 +- DNS 配置错误。 +- 防火墙或安全策略拦截。 + +排查命令: + +```bash +ip addr +ip route +ping 8.8.8.8 +ping example.com +cat /etc/resolv.conf +``` + +## systemctl service failed + +排查命令: + +```bash +systemctl status +journalctl -u -n 100 --no-pager +systemctl --failed +``` + +处理建议: + +- 先看启动失败日志，不要反复重启。 +- 检查配置文件语法。 +- 检查端口、权限、路径、依赖服务。 diff --git a/docs/troubleshooting/LINUX-INCIDENT-CHECKLIST.md b/docs/troubleshooting/LINUX-INCIDENT-CHECKLIST.md new file mode 100644 index 0000000..6ad0364 --- /dev/null +++ b/docs/troubleshooting/LINUX-INCIDENT-CHECKLIST.md @@ -0,0 +1,122 @@ +# Linux 故障应急排查清单 + +这份清单面向值班、运维和开发排障场景。建议按顺序排查: 先确认现象，再看资源，再看日志，最后处理服务和配置。 + +## 1. 确认系统状态 + +```bash +# 系统版本 +cat /etc/os-release + +# 内核版本 +uname -a + +# 当前时间和运行时长 +date +uptime + +# 最近登录 +last -n 10 +``` + +## 2. CPU 飙高 + +```bash +# 实时查看资源 +top + +# 按 CPU 排序查看进程 +ps aux --sort=-%cpu | head -n 10 + +# 查看指定进程线程 +ps -T -p +``` + +处理建议: + +- 先确认进程名称、启动用户和启动时间。 +- 不确定进程用途时，不要直接 `kill -9`。 +- Java、Node.js、Python 服务建议结合应用日志判断。 + +## 3. 内存不足 + +```bash +# 查看内存 +free -h + +# 按内存排序 +ps aux --sort=-%mem | head -n 10 + +# 查看 OOM 记录 +dmesg -T | grep -i "out of memory" +``` + +## 4. 磁盘空间满 + +```bash +# 查看磁盘空间 +df -h + +# 查看目录占用 +du -sh /* 2>/dev/null + +# 查找大文件 +find / -type f -size +500M 2>/dev/null +``` + +处理建议: + +- 优先清理日志、临时文件、旧备份。 +- 删除前先确认文件是否仍被进程占用: `lsof | grep deleted`。 +- 不建议直接删除数据库、容器、业务上传目录里的文件。 + +## 5. 服务启动失败 + +```bash +# 查看服务状态 +systemctl status + +# 查看最近日志 +journalctl -u -n 100 --no-pager + +# 查看启动耗时 +systemd-analyze blame | head +``` + +## 6. 端口不通 + +```bash +# 查看监听 +ss -tulnp + +# 测试域名解析 +nslookup example.com + +# 测试端口 +nc -vz 127.0.0.1 8080 + +# 查看防火墙 +firewall-cmd --state 2>/dev/null || ufw status 2>/dev/null +``` + +## 7. 日志快速定位 + +```bash +# 查看系统日志 +journalctl -xe --no-pager + +# 搜索错误 +grep -RniE "error|failed|exception|timeout" /var/log 2>/dev/null | head -n 50 + +# 实时看应用日志 +tail -f /path/to/app.log +``` + +## 高危操作提醒 + +| 操作 | 风险 | 建议 | +| --- | --- | --- | +| `kill -9` | 可能造成数据未刷盘 | 优先正常停止服务 | +| `rm -rf` | 不可恢复删除 | 先确认路径和备份 | +| 清空日志 | 可能丢失排障证据 | 先备份或截取关键日志 | +| 修改防火墙 | 可能断开远程连接 | 保留当前 SSH 会话 | diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..8b4926c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,110 @@ +site_name: Windows PowerShell 与 Linux 常用命令手册 +site_description: Windows PowerShell、Linux、银河麒麟、统信 UOS 常用命令中文速查手册 +site_url: https://shiwenxin123.github.io/PowerShell-Linux-/ +repo_url: https://github.com/shiwenxin123/PowerShell-Linux- +repo_name: shiwenxin123/PowerShell-Linux- + +theme: + name: material + language: zh + features: + - navigation.tabs + - navigation.sections + - navigation.top + - search.highlight + - search.suggest + +nav: + - 首页: index.md + - FAQ: FAQ.md + - 命令索引: COMMAND-INDEX.md + - 命令覆盖矩阵: COMMAND-COVERAGE-MATRIX.md + - 主手册迁移进度: MANUAL-MIGRATION.md + - 下一阶段计划: NEXT-STAGE-PLAN.md + - 命令速查表: COMMAND-CHEATSHEET.md + - 专题化手册: + - 入口: manual/README.md + - PowerShell 基础: manual/powershell/BASIC.md + - PowerShell 系统管理: manual/powershell/SYSTEM-ADMIN.md + - PowerShell 高级技巧: manual/powershell/ADVANCED-SCRIPTING.md + - Linux 基础: manual/linux/BASIC.md + - Linux 包管理: manual/linux/PACKAGE-MANAGEMENT.md + - Linux 用户组与权限: manual/linux/USERS-PERMISSIONS.md + - Shell 脚本: manual/linux/SHELL-SCRIPTING.md + - Linux 网络排查: manual/linux/NETWORK.md + - Linux 存储与日志: manual/linux/STORAGE-LOGS.md + - Linux 系统监控与日志: manual/linux/MONITORING-LOGS.md + - Linux 磁盘与 LVM: manual/linux/DISK-LVM.md + - Linux 性能调优: manual/linux/PERFORMANCE-TUNING.md + - 系统安全加固: manual/security/HARDENING.md + - 防火墙与 SELinux: manual/security/FIREWALL-SELINUX.md + - 日志轮转与审计: manual/security/LOGGING-AUDIT.md + - sudoers 与 AppArmor: manual/security/SUDOERS-APPARMOR.md + - Windows 管理命令: manual/windows/ADMIN-COMMANDS.md + - Kubernetes 进阶排查: manual/kubernetes/ADVANCED-TROUBLESHOOTING.md + - Docker 与 Kubernetes 生产级命令: manual/kubernetes/DOCKER-K8S-PRODUCTION.md + - 数据库与中间件: manual/middleware/DATABASE-MIDDLEWARE.md + - PostgreSQL/MongoDB/Elasticsearch: manual/middleware/POSTGRES-MONGO-ELASTIC.md + - 云服务器与负载均衡: manual/cloud/CLOUD-LB-TROUBLESHOOTING.md + - 集中日志与监控告警: manual/observability/LOGGING-MONITORING.md + - PromQL/LogQL/告警规则: manual/observability/PROMQL-LOGQL-ALERTS.md + - 开发与排障工具: manual/devtools/README.md + - Git、SSH、curl 与 jq: manual/devtools/GIT-SSH-CURL-JQ.md + - 巡检脚本工具化: manual/automation/HEALTH-CHECK-SCRIPTS.md + - Python 与 Node.js 跨平台脚本: manual/cross-platform/PYTHON-NODE-SCRIPTS.md + - Keepalived 高可用: manual/ha/KEEPALIVED.md + - 跨平台工具: manual/cross-platform/TOOLS.md + - PowerShell/Bash 对照: POWERSHELL-BASH-COMPARISON.md + - PowerShell: + - 实用场景: powershell/POWERSHELL-PRACTICAL.md + - Linux: + - Bash 文本处理: linux/BASH-TEXT-PROCESSING.md + - Linux 排障: + - 应急排查清单: troubleshooting/LINUX-INCIDENT-CHECKLIST.md + - 常见报错排查: troubleshooting/COMMON-ERRORS.md + - 故障案例: + - 案例库首页: cases/README.md + - 磁盘空间满: cases/DISK-FULL.md + - CPU 飙高: cases/CPU-HIGH.md + - 端口被占用: cases/PORT-IN-USE.md + - SSH 连接失败: cases/SSH-CONNECTION-FAILED.md + - Nginx 启动失败: cases/NGINX-START-FAILED.md + - Nginx 502/504: cases/NGINX-502-504.md + - MySQL 启动失败: cases/MYSQL-START-FAILED.md + - Redis 连接失败: cases/REDIS-CONNECTION-FAILED.md + - Java 服务 OOM: cases/JAVA-OOM.md + - DNS 解析失败: cases/DNS-RESOLUTION-FAILED.md + - 证书过期: cases/CERTIFICATE-EXPIRED.md + - TLS 证书链不完整: cases/TLS-CHAIN-INCOMPLETE.md + - Docker 容器反复重启: cases/DOCKER-RESTARTING.md + - Docker Compose 启动失败: cases/DOCKER-COMPOSE-FAILED.md + - Pod CrashLoopBackOff: cases/K8S-CRASHLOOPBACKOFF.md + - ImagePullBackOff: cases/K8S-IMAGEPULLBACKOFF.md + - Kubernetes DNS 异常: cases/K8S-DNS-FAILED.md + - Prometheus Target Down: cases/PROMETHEUS-TARGET-DOWN.md + - Grafana 无数据: cases/GRAFANA-NO-DATA.md + - 容器: + - Docker 与 Kubernetes: containers/DOCKER-KUBERNETES-CHEATSHEET.md + - 国产 Linux: + - 麒麟与 UOS: domestic-linux/KYLIN-UOS-COMMANDS.md + - 离线安装与软件源: domestic-linux/OFFLINE-PACKAGE-GUIDE.md + - 架构与兼容性检查: domestic-linux/ARCHITECTURE-CHECKLIST.md + - 版本差异与排查要点: domestic-linux/VERSION-DIFFERENCES.md + - 安全: + - 命令风险等级: security/RISK-LEVELS.md + - GitHub 热度优化: GITHUB-GROWTH-CHECKLIST.md + - 项目维护: + - Roadmap: ROADMAP.md + - 项目审查报告: PROJECT-AUDIT.md + - Good First Issues: GOOD-FIRST-ISSUES.md + - 维护者指南: MAINTAINER-GUIDE.md + - Release 检查清单: RELEASE-CHECKLIST.md + - v2.16.0 Release 草案: RELEASE-2.16-DRAFT.md + +markdown_extensions: + - admonition + - tables + - toc: + permalink: true + - pymdownx.superfences + - pymdownx.highlight diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..3c803d2 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +mkdocs>=1.6,<2.0 +mkdocs-material>=9.5,<10.0 +pymdown-extensions>=10.0,<11.0 diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..745321b --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,77 @@ +# 示例脚本 + +这个目录用于存放可复制、可改造的运维脚本。脚本默认偏保守，只做信息收集或生成报告，不直接删除文件、不修改系统配置。 + +## 当前脚本 + +| 脚本 | 说明 | +| --- | --- | +| `linux-health-check.sh` | Linux 基础巡检，支持模块化检查、Markdown 和 JSON 报告 | +| `windows-health-check.ps1` | Windows PowerShell 基础巡检，支持模块化检查、Markdown 和 JSON 报告 | +| `check-docs.ps1` | 文档质量检查，检查代码块、相对链接和 MkDocs 导航 | + +## 使用示例 + +Linux: + +```bash +# 直接输出到终端 +bash scripts/linux-health-check.sh + +# 同时保存报告 +bash scripts/linux-health-check.sh reports/linux-health-check.txt + +# 只检查磁盘 +bash scripts/linux-health-check.sh --module disk + +# 生成 Markdown 报告 +bash scripts/linux-health-check.sh --format markdown --output reports/linux-health-check.md + +# 生成 JSON 报告 +bash scripts/linux-health-check.sh --format json --output reports/linux-health-check.json +``` + +Windows PowerShell: + +```powershell +# 直接输出到终端 +.\scripts\windows-health-check.ps1 + +# 保存报告 +.\scripts\windows-health-check.ps1 -OutputFile reports\windows-health-check.txt + +# 只检查网络 +.\scripts\windows-health-check.ps1 -Module network + +# 生成 Markdown 报告 +.\scripts\windows-health-check.ps1 -Format markdown -OutputFile reports\windows-health-check.md + +# 生成 JSON 报告 +.\scripts\windows-health-check.ps1 -Format json -OutputFile reports\windows-health-check.json +``` + +## 支持模块 + +| 模块 | 说明 | +| --- | --- | +| `all` | 默认，执行全部检查 | +| `system` | 系统版本、运行时间、内存等 | +| `disk` | 磁盘空间、inode 或驱动器信息 | +| `network` | 监听端口和网络路由 | +| `service` | 异常服务或未运行服务 | +| `process` | CPU 和内存占用较高的进程 | + +## 退出码 + +| 退出码 | 含义 | +| --- | --- | +| `0` | 巡检正常完成且无告警 | +| `1` | 巡检完成但存在告警或部分模块异常 | +| `2` | 参数错误 | +| `3` | 脚本内部异常或关键输出写入失败 | + +## 使用建议 + +- 生产环境执行前先阅读脚本内容。 +- 需要管理员权限的命令请在受控环境执行。 +- 输出报告里可能包含主机名、IP、进程名等信息，公开分享前请脱敏。 diff --git a/scripts/check-docs.ps1 b/scripts/check-docs.ps1 new file mode 100644 index 0000000..555afaa --- /dev/null +++ b/scripts/check-docs.ps1 @@ -0,0 +1,91 @@ +param( + [string]$Root = (Resolve-Path ".").Path +) + +$ErrorActionPreference = "Stop" +$failures = New-Object System.Collections.Generic.List[string] + +$markdownFiles = Get-ChildItem -Path $Root -Recurse -File -Filter *.md + +foreach ($file in $markdownFiles) { + $fenceCount = (Select-String -Path $file.FullName -Pattern '```' -Encoding UTF8).Count + if ($fenceCount % 2 -ne 0) { + $failures.Add("Unbalanced code fence: $($file.FullName)") + } +} + +$conflictPattern = '^(<<<<<<<|>>>>>>>|=======$)' +$scanFiles = Get-ChildItem -Path $Root -Recurse -File -Include *.md,*.yml,*.yaml,*.ps1,*.sh,requirements.txt +foreach ($file in $scanFiles) { + if ($file.Name -eq "check-docs.ps1") { + continue + } + + $matches = Select-String -Path $file.FullName -Pattern $conflictPattern -Encoding UTF8 -ErrorAction SilentlyContinue + foreach ($match in $matches) { + $failures.Add("Suspicious marker: $($file.FullName):$($match.LineNumber)") + } +} + +$linkRegex = [regex]'\[[^\]]+\]\(([^)]+)\)' +foreach ($file in $markdownFiles) { + $text = Get-Content -Raw -Encoding UTF8 -Path $file.FullName + foreach ($match in $linkRegex.Matches($text)) { + $link = $match.Groups[1].Value + if ($link -match '^(https?:|mailto:|#)' -or [string]::IsNullOrWhiteSpace($link)) { + continue + } + + $path = $link.Split('#')[0] + if ([string]::IsNullOrWhiteSpace($path)) { + continue + } + + $decoded = [uri]::UnescapeDataString($path) + $target = Join-Path $file.DirectoryName $decoded + if (-not (Test-Path $target)) { + $relativeFile = Resolve-Path -Path $file.FullName -Relative + $failures.Add("Broken relative link: $relativeFile -> $link") + } + } +} + +$secretPatterns = @( + '-----BEGIN (RSA |DSA |EC |OPENSSH |)PRIVATE KEY-----', + 'AKIA[0-9A-Z]{16}', + '(?i)(password|passwd|token|secret|api[_-]?key)\s*[:=]\s*["''][^"'']{8,}["'']' +) + +$secretScanFiles = Get-ChildItem -Path $Root -Recurse -File -Include *.md,*.yml,*.yaml,*.ps1,*.sh,*.json,*.env +foreach ($file in $secretScanFiles) { + if ($file.FullName -match '\\.git\\') { + continue + } + + foreach ($pattern in $secretPatterns) { + $matches = Select-String -Path $file.FullName -Pattern $pattern -Encoding UTF8 -ErrorAction SilentlyContinue + foreach ($match in $matches) { + $relativeFile = Resolve-Path -Path $file.FullName -Relative + $failures.Add("Possible secret: ${relativeFile}:$($match.LineNumber)") + } + } +} + +$mkdocs = Join-Path $Root "mkdocs.yml" +if (Test-Path $mkdocs) { + $docsRoot = Join-Path $Root "docs" + $navPaths = Select-String -Path $mkdocs -Pattern '([A-Za-z0-9_./-]+\.md)' -Encoding UTF8 | ForEach-Object { $_.Matches.Value } + foreach ($navPath in $navPaths) { + $target = Join-Path $docsRoot $navPath + if (-not (Test-Path $target)) { + $failures.Add("Missing MkDocs nav target: $navPath") + } + } +} + +if ($failures.Count -gt 0) { + $failures | ForEach-Object { Write-Error $_ } + exit 1 +} + +Write-Output "Documentation checks OK" diff --git a/scripts/linux-health-check.sh b/scripts/linux-health-check.sh new file mode 100644 index 0000000..5509c3c --- /dev/null +++ b/scripts/linux-health-check.sh @@ -0,0 +1,390 @@ +#!/usr/bin/env bash +set -u + +MODULE="all" +FORMAT="text" +OUTPUT_FILE="" +WARNINGS_COUNT=0 +ERRORS_COUNT=0 + +usage() { + cat <<'EOF' +Usage: bash scripts/linux-health-check.sh [--module all|system|disk|network|service|process] [--format text|markdown|json] [--output reports/linux.md] + +Examples: + bash scripts/linux-health-check.sh + bash scripts/linux-health-check.sh --module disk + bash scripts/linux-health-check.sh --format markdown --output reports/linux-health-check.md + bash scripts/linux-health-check.sh --format json --output reports/linux-health-check.json +EOF +} + +fail_param() { + echo "$1" >&2 + usage >&2 + exit 2 +} + +while [ "$#" -gt 0 ]; do + case "$1" in + --module) + [ "$#" -ge 2 ] || fail_param "Missing value for --module" + MODULE="$2" + shift 2 + ;; + --format) + [ "$#" -ge 2 ] || fail_param "Missing value for --format" + FORMAT="$2" + shift 2 + ;; + --output) + [ "$#" -ge 2 ] || fail_param "Missing value for --output" + OUTPUT_FILE="$2" + shift 2 + ;; + -h|--help) + usage + exit 0 + ;; + -*) + fail_param "Unknown option: $1" + ;; + *) + # Backward compatibility: first positional argument is treated as output path. + OUTPUT_FILE="$1" + shift + ;; + esac +done + +case "$MODULE" in + all|system|disk|network|service|process) ;; + *) fail_param "Unsupported module: $MODULE" ;; +esac + +case "$FORMAT" in + text|markdown|json) ;; + *) fail_param "Unsupported format: $FORMAT" ;; +esac + +if [ -n "$OUTPUT_FILE" ]; then + if ! mkdir -p "$(dirname "$OUTPUT_FILE")"; then + echo "Failed to create output directory for: $OUTPUT_FILE" >&2 + exit 3 + fi +fi + +json_escape() { + local value=${1-} + value=${value//\\/\\\\} + value=${value//\"/\\\"} + value=${value//$'\n'/\\n} + value=${value//$'\r'/\\r} + value=${value//$'\t'/\\t} + printf '%s' "$value" +} + +section() { + if [ "$FORMAT" = "markdown" ]; then + echo + echo "## $1" + echo + else + echo + echo "== $1 ==" + fi +} + +run_block() { + "$@" 2>&1 || true +} + +should_run() { + [ "$MODULE" = "all" ] || [ "$MODULE" = "$1" ] +} + +module_status() { + local warnings=$1 + local errors=$2 + if [ "$errors" -gt 0 ]; then + echo "error" + elif [ "$warnings" -gt 0 ]; then + echo "warning" + else + echo "ok" + fi +} + +run_json_command() { + local label=$1 + shift + local output + local rc + local label_escaped command_escaped output_escaped + output=$("$@" 2>&1) + rc=$? + if [ "$rc" -ne 0 ]; then + MODULE_WARNINGS=$((MODULE_WARNINGS + 1)) + fi + + label_escaped=$(json_escape "$label") + command_escaped=$(json_escape "$*") + output_escaped=$(json_escape "$output") + COMMAND_JSON="{\"name\":\"$label_escaped\",\"command\":\"$command_escaped\",\"exit_code\":$rc,\"output\":\"$output_escaped\"}" +} + +missing_command_json() { + local command_name=$1 + local command_escaped message_escaped + MODULE_WARNINGS=$((MODULE_WARNINGS + 1)) + command_escaped=$(json_escape "$command_name") + message_escaped=$(json_escape "Command not available: $command_name") + WARNING_JSON="{\"name\":\"$command_escaped\",\"message\":\"$message_escaped\"}" +} + +set_module_json() { + local name=$1 + local commands=$2 + local warnings=$3 + local errors=$4 + local warning_count=$5 + local error_count=$6 + local status + status=$(module_status "$warning_count" "$error_count") + WARNINGS_COUNT=$((WARNINGS_COUNT + warning_count)) + ERRORS_COUNT=$((ERRORS_COUNT + error_count)) + + MODULE_JSON="\"$name\":{\"status\":\"$status\",\"commands\":[$commands],\"warnings\":[$warnings],\"errors\":[$errors]}" +} + +skipped_json_module() { + local name=$1 + MODULE_JSON="\"$name\":{\"status\":\"skipped\",\"commands\":[],\"warnings\":[],\"errors\":[]}" +} + +collect_system_json() { + MODULE_WARNINGS=0 + MODULE_ERRORS=0 + local commands="" + local warnings="" + run_json_command uname uname -a + commands="$COMMAND_JSON" + if [ -f /etc/os-release ]; then + run_json_command os-release cat /etc/os-release + commands="$commands,$COMMAND_JSON" + else + MODULE_WARNINGS=$((MODULE_WARNINGS + 1)) + missing_command_json /etc/os-release + warnings="$WARNING_JSON" + fi + run_json_command uptime uptime + commands="$commands,$COMMAND_JSON" + run_json_command memory free -h + commands="$commands,$COMMAND_JSON" + set_module_json system "$commands" "$warnings" "" "$MODULE_WARNINGS" "$MODULE_ERRORS" +} + +collect_disk_json() { + MODULE_WARNINGS=0 + MODULE_ERRORS=0 + local commands="" + run_json_command disk df -h + commands="$COMMAND_JSON" + run_json_command inodes df -i + commands="$commands,$COMMAND_JSON" + set_module_json disk "$commands" "" "" "$MODULE_WARNINGS" "$MODULE_ERRORS" +} + +collect_process_json() { + MODULE_WARNINGS=0 + MODULE_ERRORS=0 + local commands="" + run_json_command top_cpu sh -c "ps aux --sort=-%cpu | head -n 10" + commands="$COMMAND_JSON" + run_json_command top_memory sh -c "ps aux --sort=-%mem | head -n 10" + commands="$commands,$COMMAND_JSON" + set_module_json process "$commands" "" "" "$MODULE_WARNINGS" "$MODULE_ERRORS" +} + +collect_network_json() { + MODULE_WARNINGS=0 + MODULE_ERRORS=0 + local commands="" + local warnings="" + if command -v ss >/dev/null 2>&1; then + run_json_command listening_ports ss -tulnp + commands="$COMMAND_JSON" + elif command -v netstat >/dev/null 2>&1; then + run_json_command listening_ports netstat -tulnp + commands="$COMMAND_JSON" + else + missing_command_json ss + warnings="$WARNING_JSON" + fi + + if command -v ip >/dev/null 2>&1; then + if [ -n "$commands" ]; then + run_json_command routes ip route + commands="$commands,$COMMAND_JSON" + else + run_json_command routes ip route + commands="$COMMAND_JSON" + fi + else + if [ -n "$warnings" ]; then + missing_command_json ip + warnings="$warnings,$WARNING_JSON" + else + missing_command_json ip + warnings="$WARNING_JSON" + fi + fi + set_module_json network "$commands" "$warnings" "" "$MODULE_WARNINGS" "$MODULE_ERRORS" +} + +collect_service_json() { + MODULE_WARNINGS=0 + MODULE_ERRORS=0 + local commands="" + local warnings="" + if command -v systemctl >/dev/null 2>&1; then + run_json_command failed_services systemctl --failed --no-pager + commands="$COMMAND_JSON" + else + missing_command_json systemctl + warnings="$WARNING_JSON" + fi + set_module_json service "$commands" "$warnings" "" "$MODULE_WARNINGS" "$MODULE_ERRORS" +} + +json_report() { + local timestamp + local hostname_value + local os_value + timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ") + hostname_value=$(hostname 2>/dev/null || echo "unknown") + os_value=$(uname -s 2>/dev/null || echo "Linux") + + local system_json disk_json network_json service_json process_json + if should_run system; then collect_system_json; else skipped_json_module system; fi + system_json="$MODULE_JSON" + if should_run disk; then collect_disk_json; else skipped_json_module disk; fi + disk_json="$MODULE_JSON" + if should_run network; then collect_network_json; else skipped_json_module network; fi + network_json="$MODULE_JSON" + if should_run service; then collect_service_json; else skipped_json_module service; fi + service_json="$MODULE_JSON" + if should_run process; then collect_process_json; else skipped_json_module process; fi + process_json="$MODULE_JSON" + + local status="ok" + if [ "$ERRORS_COUNT" -gt 0 ]; then + status="error" + elif [ "$WARNINGS_COUNT" -gt 0 ]; then + status="warning" + fi + + local os_escaped hostname_escaped timestamp_escaped module_escaped status_escaped + os_escaped=$(json_escape "$os_value") + hostname_escaped=$(json_escape "$hostname_value") + timestamp_escaped=$(json_escape "$timestamp") + module_escaped=$(json_escape "$MODULE") + status_escaped=$(json_escape "$status") + REPORT=$(printf '{"metadata":{"os":"%s","hostname":"%s","timestamp":"%s","module":"%s","format":"json","script":"linux-health-check.sh"},"modules":{%s,%s,%s,%s,%s},"summary":{"status":"%s","warnings_count":%s,"errors_count":%s},"errors":[]}\n' \ + "$os_escaped" "$hostname_escaped" "$timestamp_escaped" "$module_escaped" \ + "$system_json" "$disk_json" "$network_json" "$service_json" "$process_json" \ + "$status_escaped" "$WARNINGS_COUNT" "$ERRORS_COUNT") +} + +text_or_markdown_report() { + if [ "$FORMAT" = "markdown" ]; then + echo "# Linux Health Check" + echo + echo "- Time: $(date)" + echo "- Module: $MODULE" + else + echo "== Linux Health Check ==" + echo "Time: $(date)" + echo "Module: $MODULE" + fi + + if should_run system; then + section "System" + if [ "$FORMAT" = "markdown" ]; then echo '```text'; fi + run_block uname -a + if [ -f /etc/os-release ]; then run_block cat /etc/os-release; fi + if [ "$FORMAT" = "markdown" ]; then echo '```'; fi + section "Uptime" + if [ "$FORMAT" = "markdown" ]; then echo '```text'; fi + run_block uptime + if [ "$FORMAT" = "markdown" ]; then echo '```'; fi + section "Memory" + if [ "$FORMAT" = "markdown" ]; then echo '```text'; fi + run_block free -h + if [ "$FORMAT" = "markdown" ]; then echo '```'; fi + fi + + if should_run disk; then + section "Disk" + if [ "$FORMAT" = "markdown" ]; then echo '```text'; fi + run_block df -h + run_block df -i + if [ "$FORMAT" = "markdown" ]; then echo '```'; fi + fi + + if should_run process; then + section "Top Processes" + if [ "$FORMAT" = "markdown" ]; then echo '```text'; fi + run_block sh -c "ps aux --sort=-%cpu | head -n 10" + run_block sh -c "ps aux --sort=-%mem | head -n 10" + if [ "$FORMAT" = "markdown" ]; then echo '```'; fi + fi + + if should_run network; then + section "Network" + if [ "$FORMAT" = "markdown" ]; then echo '```text'; fi + if command -v ss >/dev/null 2>&1; then + run_block ss -tulnp + else + run_block sh -c "netstat -tulnp 2>/dev/null" + fi + run_block ip route + if [ "$FORMAT" = "markdown" ]; then echo '```'; fi + fi + + if should_run service; then + section "Failed Services" + if [ "$FORMAT" = "markdown" ]; then echo '```text'; fi + if command -v systemctl >/dev/null 2>&1; then + run_block systemctl --failed --no-pager + else + echo "systemctl not available" + fi + if [ "$FORMAT" = "markdown" ]; then echo '```'; fi + fi + + section "Done" + if [ -n "$OUTPUT_FILE" ]; then echo "Report saved to: $OUTPUT_FILE"; fi +} + +if [ "$FORMAT" = "json" ]; then + json_report || exit 3 +else + REPORT=$(text_or_markdown_report) || exit 3 +fi + +if [ -n "$OUTPUT_FILE" ]; then + if ! printf '%s\n' "$REPORT" | tee "$OUTPUT_FILE"; then + echo "Failed to write output file: $OUTPUT_FILE" >&2 + exit 3 + fi +else + printf '%s\n' "$REPORT" +fi + +if [ "$ERRORS_COUNT" -gt 0 ]; then + exit 3 +elif [ "$WARNINGS_COUNT" -gt 0 ]; then + exit 1 +fi +exit 0 diff --git a/scripts/windows-health-check.ps1 b/scripts/windows-health-check.ps1 new file mode 100644 index 0000000..a5fd97b --- /dev/null +++ b/scripts/windows-health-check.ps1 @@ -0,0 +1,289 @@ +param( + [string]$Module = "all", + + [string]$Format = "text", + + [string]$OutputFile +) + +$ErrorActionPreference = "Continue" +$validModules = @("all", "system", "disk", "network", "service", "process") +$validFormats = @("text", "markdown", "json") + +if ($validModules -notcontains $Module) { + Write-Error "Invalid module '$Module'. Valid values: $($validModules -join ', ')" + exit 2 +} + +if ($validFormats -notcontains $Format) { + Write-Error "Invalid format '$Format'. Valid values: $($validFormats -join ', ')" + exit 2 +} + +$lines = New-Object System.Collections.Generic.List[string] +$script:WarningsCount = 0 +$script:ErrorsCount = 0 +$script:ReportModules = [ordered]@{} +$script:TopLevelErrors = New-Object System.Collections.Generic.List[object] + +function Add-Line { + param([string]$Text = "") + $script:lines.Add($Text) +} + +function Should-Run { + param([string]$Name) + return $Module -eq "all" -or $Module -eq $Name +} + +function Invoke-HealthCommand { + param( + [string]$Name, + [scriptblock]$Command + ) + + try { + $previousErrorActionPreference = $ErrorActionPreference + $ErrorActionPreference = "Stop" + $output = & $Command 2>&1 | Out-String + [pscustomobject]@{ + name = $Name + command = $Command.ToString().Trim() + exit_code = 0 + output = $output.TrimEnd() + } + } + catch { + [pscustomobject]@{ + name = $Name + command = $Command.ToString().Trim() + exit_code = 1 + output = $_.Exception.Message + } + } + finally { + $ErrorActionPreference = $previousErrorActionPreference + } +} + +function New-ModuleResult { + param( + [string]$Name, + [object[]]$Commands = @(), + [object[]]$Warnings = @(), + [object[]]$Errors = @(), + [string]$Status + ) + + $derivedWarnings = @() + foreach ($command in $Commands) { + if ($command.exit_code -ne 0) { + $derivedWarnings += [pscustomobject]@{ + name = $command.name + message = "Command returned exit code $($command.exit_code)" + } + } + } + $allWarnings = @($Warnings) + @($derivedWarnings) + + if (-not $Status) { + if ($Errors.Count -gt 0) { + $Status = "error" + } + elseif ($allWarnings.Count -gt 0) { + $Status = "warning" + } + else { + $Status = "ok" + } + } + + $script:WarningsCount += $allWarnings.Count + $script:ErrorsCount += $Errors.Count + + [pscustomobject]@{ + status = $Status + commands = @($Commands) + warnings = @($allWarnings) + errors = @($Errors) + } +} + +function New-SkippedModule { + [pscustomobject]@{ + status = "skipped" + commands = @() + warnings = @() + errors = @() + } +} + +function Add-TextSection { + param( + [string]$Title, + [object[]]$Commands + ) + + Add-Line + if ($Format -eq "markdown") { + Add-Line "## $Title" + Add-Line + Add-Line '```text' + } + else { + Add-Line "== $Title ==" + } + + foreach ($command in $Commands) { + if ($command.output) { + Add-Line $command.output + } + } + + if ($Format -eq "markdown") { + Add-Line '```' + } +} + +function Get-SystemModule { + $commands = @( + Invoke-HealthCommand "computer_info" { Get-ComputerInfo | Select-Object CsName, WindowsProductName, WindowsVersion, OsArchitecture } + ) + New-ModuleResult -Name "system" -Commands $commands +} + +function Get-DiskModule { + $commands = @( + Invoke-HealthCommand "drives" { Get-PSDrive -PSProvider FileSystem | Select-Object Name, Used, Free } + ) + New-ModuleResult -Name "disk" -Commands $commands +} + +function Get-ProcessModule { + $commands = @( + Invoke-HealthCommand "top_cpu_processes" { Get-Process | Sort-Object CPU -Descending | Select-Object -First 10 Name, Id, CPU, WorkingSet } + ) + New-ModuleResult -Name "process" -Commands $commands +} + +function Get-ServiceModule { + $commands = @( + Invoke-HealthCommand "services_not_running" { Get-Service | Where-Object Status -ne "Running" | Select-Object -First 20 Name, Status, StartType } + ) + New-ModuleResult -Name "service" -Commands $commands +} + +function Get-NetworkModule { + $commands = @( + Invoke-HealthCommand "listening_tcp_ports" { Get-NetTCPConnection -State Listen | Select-Object LocalAddress, LocalPort, OwningProcess } + ) + New-ModuleResult -Name "network" -Commands $commands +} + +$moduleOrder = @("system", "disk", "network", "service", "process") +foreach ($moduleName in $moduleOrder) { + if (-not (Should-Run $moduleName)) { + $script:ReportModules[$moduleName] = New-SkippedModule + continue + } + + switch ($moduleName) { + "system" { $script:ReportModules[$moduleName] = Get-SystemModule } + "disk" { $script:ReportModules[$moduleName] = Get-DiskModule } + "network" { $script:ReportModules[$moduleName] = Get-NetworkModule } + "service" { $script:ReportModules[$moduleName] = Get-ServiceModule } + "process" { $script:ReportModules[$moduleName] = Get-ProcessModule } + } +} + +$summaryStatus = "ok" +if ($script:ErrorsCount -gt 0) { + $summaryStatus = "error" +} +elseif ($script:WarningsCount -gt 0) { + $summaryStatus = "warning" +} + +$hostnameValue = $env:COMPUTERNAME +if (-not $hostnameValue) { + $hostnameValue = [System.Net.Dns]::GetHostName() +} + +$metadata = New-Object PSObject +$metadata | Add-Member -MemberType NoteProperty -Name "os" -Value "Windows" +$metadata | Add-Member -MemberType NoteProperty -Name "hostname" -Value $hostnameValue +$metadata | Add-Member -MemberType NoteProperty -Name "timestamp" -Value (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ") +$metadata | Add-Member -MemberType NoteProperty -Name "module" -Value $Module +$metadata | Add-Member -MemberType NoteProperty -Name "format" -Value $Format +$metadata | Add-Member -MemberType NoteProperty -Name "script" -Value "windows-health-check.ps1" + +$modulesObject = New-Object PSObject +foreach ($moduleName in $moduleOrder) { + $modulesObject | Add-Member -MemberType NoteProperty -Name $moduleName -Value $script:ReportModules[$moduleName] +} + +$summary = New-Object PSObject +$summary | Add-Member -MemberType NoteProperty -Name "status" -Value $summaryStatus +$summary | Add-Member -MemberType NoteProperty -Name "warnings_count" -Value $script:WarningsCount +$summary | Add-Member -MemberType NoteProperty -Name "errors_count" -Value $script:ErrorsCount + +$report = New-Object PSObject +$report | Add-Member -MemberType NoteProperty -Name "metadata" -Value $metadata +$report | Add-Member -MemberType NoteProperty -Name "modules" -Value $modulesObject +$report | Add-Member -MemberType NoteProperty -Name "summary" -Value $summary +$topLevelErrors = @() +foreach ($errorItem in $script:TopLevelErrors) { + $topLevelErrors += $errorItem +} +$report | Add-Member -MemberType NoteProperty -Name "errors" -Value ([object[]]$topLevelErrors) + +if ($Format -eq "json") { + $rendered = $report | ConvertTo-Json -Depth 8 +} +else { + if ($Format -eq "markdown") { + Add-Line "# Windows Health Check" + Add-Line + Add-Line "- Time: $(Get-Date)" + Add-Line "- Module: $Module" + } + else { + Add-Line "== Windows Health Check ==" + Add-Line "Time: $(Get-Date)" + Add-Line "Module: $Module" + } + + foreach ($moduleName in $moduleOrder) { + $moduleResult = $script:ReportModules[$moduleName] + if ($moduleResult.status -ne "skipped") { + Add-TextSection -Title $moduleName -Commands $moduleResult.commands + } + } + + Add-Line + if ($Format -eq "markdown") { + Add-Line "## Done" + } + else { + Add-Line "== Done ==" + } + $rendered = ($lines -join [Environment]::NewLine) +} + +if ($OutputFile) { + $parent = Split-Path -Parent $OutputFile + if ($parent) { + New-Item -ItemType Directory -Force -Path $parent | Out-Null + } + $rendered | Set-Content -Path $OutputFile -Encoding UTF8 +} + +Write-Output $rendered + +if ($script:ErrorsCount -gt 0) { + exit 3 +} +elseif ($script:WarningsCount -gt 0) { + exit 1 +} +exit 0