maintenance: extend SFTP connection options

[zqr10159]

Summary

• Pin SFTP server identity to one or more configured SHA-256 host-key fingerprints.
• Accept a current and next fingerprint together so operators can rotate host keys without an outage.
• Keep pre-upgrade SFTP monitors running by explicitly migrating only legacy records with no host-key policy to a temporary compatibility flag.
• Emit controlled warnings for that migration and for every connection that still skips verification.
• Mark the unsafe UI option as dangerous and conditional on SFTP, and document trusted fingerprint acquisition, upgrade, and rotation in English and Chinese.

Regression proof

The rotation contract was first run against the previous PR head. It rejected the second verified key because the implementation treated the entire multi-line value as one fingerprint. The legacy-upgrade contract also had no implementation on the previous head. Both outcome paths pass with this revision.

Validation

• Focused protocol, verifier, and migration contracts: 15 tests passed (FtpProtocolTest, FtpCollectImplTest, and SftpHostKeyCompatibilityMigrationTest).
• YamlCheckScript: all monitor definitions parsed successfully.
• ./mvnw -pl hertzbeat-startup -am -DskipTests package: all 24 reactor modules passed and produced the source-built startup artifact.
• Checkstyle and git diff --check: passed.
• Touched Java and test files contain no hard-coded CJK text; localized YAML and documentation intentionally contain locale content.

Upgrade behavior

Existing ftp monitors with SFTP enabled and neither a fingerprint nor an explicit verification policy receive insecureSkipVerify=true once, before scheduler initialization. This preserves collection but produces warnings until the operator verifies fingerprints, adds them, disables the unsafe option, and runs detection. Pinned and previously migrated monitors are not changed. New monitors and newly imported configurations remain fail-closed unless the operator explicitly selects the dangerous temporary option.

ssh-keyscan is documented only as a way to retrieve a key, not as proof of identity. Operators must compare the resulting fingerprint through a trusted channel.

AI assistance: used for draft implementation and test iteration.
Human validation: the old-head rotation contract failed; focused outcome tests, YAML parsing, Checkstyle, whitespace checks, and the 24-module startup package proof passed.
Risk notes: upgraded monitors remain temporarily unauthenticated until an operator completes the documented pinning step; warnings make this compatibility state visible.

[zqr10159]

Author remediation update:

The rollout path now preserves existing SFTP monitors through an explicit one-time compatibility migration instead of making them fail immediately. New configurations still fail closed unless they provide a trusted fingerprint or explicitly select the dangerous compatibility option. Multiple fingerprints are accepted for current and next key rotation, unsafe connections emit controlled warnings, and the UI plus English and Chinese docs explain trusted acquisition, upgrade, rotation, and exit steps.

Protocol, verifier, and migration tests passed (15), monitor YAML parsing passed, and the 24-module startup source package passed. GitHub checks are currently queued. Maintainer review remains required.

[zqr10159]

CI follow-up: the only failing check after the remediation is DOC CI Dead Link Check. It was rerun once and failed again on the same unchanged historical URL, https://gitee.com/hertzbeat/hertzbeat, returning HTTP 405. The changed SFTP documentation passed Markdown and filename checks and adds no failing external link. Backend build, Maven E2E, image E2E, license, and label checks all passed. I am leaving the unrelated global link configuration and historical pages out of this single-purpose PR; the DOC CI result should be retried after the external endpoint or repository-wide link policy is addressed.

[zqr10159]

DOC CI has now passed on the unchanged current head (6a368854b0). The clean rerun completed Markdown, filename, dead-link, dependency-install, and documentation-build steps successfully. The earlier Gitee 405 was transient; no unrelated link-check policy change was needed. Together with the already green backend build, Maven E2E, image E2E, license, and label checks, this removes the remaining CI blocker.