feat: signed releases and a host-side updater for container nodes
CI signs the image digest of each agent and probe release; the panel only stores and forwards it. Nodes write the manifest to their data directory and a host updater verifies the signature with a local public key, pulls by digest, restarts the unit and rolls back when it is unhealthy. The panel can list releases, ask a node to update and show the reported update state.
This commit is contained in:
justme committed
1 parent
48072737c9
commit
0a66f5e07a
26 files changed
+1384
-215
No files matched your search
@@ -36,6 +36,11 @@ steps:
|
||||
ZOT_USERNAME: justme
|
||||
ZOT_SECRET:
|
||||
from_secret: zot_secret
|
||||
RELEASE_API_URL: https://mo.oeo.one
|
||||
RELEASE_SIGNING_KEY:
|
||||
from_secret: release_signing_key
|
||||
RELEASE_API_TOKEN:
|
||||
from_secret: release_api_token
|
||||
commands:
|
||||
- bash ci/build-main-amd64.sh agent
|
||||
depends_on: []
|
||||
@@ -48,6 +53,11 @@ steps:
|
||||
ZOT_USERNAME: justme
|
||||
ZOT_SECRET:
|
||||
from_secret: zot_secret
|
||||
RELEASE_API_URL: https://mo.oeo.one
|
||||
RELEASE_SIGNING_KEY:
|
||||
from_secret: release_signing_key
|
||||
RELEASE_API_TOKEN:
|
||||
from_secret: release_api_token
|
||||
commands:
|
||||
- bash ci/build-main-amd64.sh probe
|
||||
depends_on: []
|
||||
@@ -25,6 +25,7 @@ public sealed class AgentApp : IDisposable
|
||||
private readonly TaskCompletionSource _ready = new(TaskCreationOptions.RunContinuationsAsynchronously);
|
||||
private readonly AgentAdmission _admission;
|
||||
private readonly Outbox _outbox = new(64 << 20);
|
||||
private readonly UpdateBridge _update;
|
||||
private readonly BackendUplink _uplink;
|
||||
private readonly UdpMux _udp;
|
||||
private readonly TcpAcceptor _tcp;
|
||||
@@ -34,8 +35,10 @@ public sealed class AgentApp : IDisposable
|
||||
private readonly TestRunner _tests;
|
||||
private readonly FleetLink _link;
|
||||
|
||||
public AgentApp(AgentConfig config, LoadedNodeIdentity identity, TimeProvider time, INodeLog log)
|
||||
/// <param name="dataDirectory">配置目录（容器里的 <c>/etc/monitor</c>）：宿主机更新器和节点在这里交换清单、请求和状态。</param>
|
||||
public AgentApp(AgentConfig config, LoadedNodeIdentity identity, string dataDirectory, TimeProvider time, INodeLog log)
|
||||
{
|
||||
_update = new UpdateBridge(dataDirectory, new ConfigStore(dataDirectory).Write, log);
|
||||
_config = config;
|
||||
_identity = identity;
|
||||
_time = time;
|
||||
@@ -200,6 +203,24 @@ public sealed class AgentApp : IDisposable
|
||||
(_, cancel, _) => ValueTask.FromResult(Result<TestRunResult>.Ok(new TestRunResult { Accepted = _tests.Cancel(cancel.TestId) })));
|
||||
}
|
||||
|
||||
if (Allow(MonitorMethods.UpdateOffer))
|
||||
{
|
||||
router.OnNotify(MonitorMethods.UpdateOffer, MonitorJsonContext.Default.UpdateOfferParams, (_, offer, _) =>
|
||||
{
|
||||
_update.WriteOffer(offer);
|
||||
return ValueTask.CompletedTask;
|
||||
});
|
||||
}
|
||||
|
||||
if (Allow(MonitorMethods.UpdateApply))
|
||||
{
|
||||
router.OnNotify(MonitorMethods.UpdateApply, MonitorJsonContext.Default.UpdateOfferParams, (_, _, _) =>
|
||||
{
|
||||
_update.RequestApply();
|
||||
return ValueTask.CompletedTask;
|
||||
});
|
||||
}
|
||||
|
||||
if (Allow(MonitorMethods.ProbeDisconnect))
|
||||
{
|
||||
router.On(
|
||||
@@ -270,6 +291,7 @@ public sealed class AgentApp : IDisposable
|
||||
DroppedInvalid = _counters.DroppedInvalid,
|
||||
DroppedRateLimited = _counters.DroppedRateLimited,
|
||||
QueueBytes = _outbox.PendingBytes,
|
||||
Update = _update.ReadStatus(),
|
||||
};
|
||||
_lastIn = packetsIn;
|
||||
_lastOut = packetsOut;
|
||||
|
||||
@@ -35,7 +35,7 @@ catch (Exception ex) when (ex is IOException or InvalidDataException or InvalidO
|
||||
|
||||
using (identity)
|
||||
{
|
||||
using var app = new AgentApp(config, identity, time, log);
|
||||
using var app = new AgentApp(config, identity, Path.GetDirectoryName(Path.GetFullPath(configPath))!, time, log);
|
||||
await ServiceShell.RunAsync(app.RunAsync, log);
|
||||
}
|
||||
|
||||
|
||||
+297
-1
@@ -3696,7 +3696,7 @@
|
||||
"tags": [
|
||||
"admin-build"
|
||||
],
|
||||
"summary": "Version, tag, commit and build time of the backend and every agent and probe",
|
||||
"summary": "Version, tag, commit, build time and update state of the backend and every agent and probe",
|
||||
"operationId": "build_info_get",
|
||||
"responses": {
|
||||
"200": {
|
||||
@@ -3732,6 +3732,175 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/admin/releases": {
|
||||
"get": {
|
||||
"tags": [
|
||||
"admin-build"
|
||||
],
|
||||
"summary": "The latest signed release manifest of each component",
|
||||
"operationId": "releases_list",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/PageDtoOfReleaseDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "Unauthorized",
|
||||
"content": {
|
||||
"application/problem+json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ProblemDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Forbidden",
|
||||
"content": {
|
||||
"application/problem+json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ProblemDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"tags": [
|
||||
"admin-build"
|
||||
],
|
||||
"summary": "Register a CI-signed release manifest; online nodes get it right away (their updaters verify the signature)",
|
||||
"operationId": "releases_publish",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/PublishReleaseRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": true
|
||||
},
|
||||
"responses": {
|
||||
"201": {
|
||||
"description": "Created",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ReleaseDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"content": {
|
||||
"application/problem+json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ProblemDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "Unauthorized",
|
||||
"content": {
|
||||
"application/problem+json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ProblemDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Forbidden",
|
||||
"content": {
|
||||
"application/problem+json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ProblemDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"409": {
|
||||
"description": "Conflict",
|
||||
"content": {
|
||||
"application/problem+json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ProblemDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/admin/nodes/{id}/update": {
|
||||
"post": {
|
||||
"tags": [
|
||||
"admin-build"
|
||||
],
|
||||
"summary": "Ask an online agent or probe to install the release it has been offered",
|
||||
"operationId": "nodes_update",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"204": {
|
||||
"description": "No Content",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": { }
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "Unauthorized",
|
||||
"content": {
|
||||
"application/problem+json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ProblemDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Forbidden",
|
||||
"content": {
|
||||
"application/problem+json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ProblemDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"409": {
|
||||
"description": "Conflict",
|
||||
"content": {
|
||||
"application/problem+json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ProblemDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/healthz": {
|
||||
"get": {
|
||||
"tags": [
|
||||
@@ -5540,6 +5709,16 @@
|
||||
"null",
|
||||
"string"
|
||||
]
|
||||
},
|
||||
"update": {
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "null"
|
||||
},
|
||||
{
|
||||
"$ref": "#/components/schemas/NodeUpdateDto"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -5612,6 +5791,49 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"NodeUpdateDto": {
|
||||
"required": [
|
||||
"state",
|
||||
"current_digest",
|
||||
"available_tag",
|
||||
"available_version",
|
||||
"error",
|
||||
"at"
|
||||
],
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"state": {
|
||||
"type": "string"
|
||||
},
|
||||
"current_digest": {
|
||||
"type": [
|
||||
"null",
|
||||
"string"
|
||||
]
|
||||
},
|
||||
"available_tag": {
|
||||
"type": [
|
||||
"null",
|
||||
"string"
|
||||
]
|
||||
},
|
||||
"available_version": {
|
||||
"type": [
|
||||
"null",
|
||||
"string"
|
||||
]
|
||||
},
|
||||
"error": {
|
||||
"type": [
|
||||
"null",
|
||||
"string"
|
||||
]
|
||||
},
|
||||
"at": {
|
||||
"format": "date-time"
|
||||
}
|
||||
}
|
||||
},
|
||||
"OverviewDto": {
|
||||
"required": [
|
||||
"range",
|
||||
@@ -5989,6 +6211,27 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"PageDtoOfReleaseDto": {
|
||||
"required": [
|
||||
"items",
|
||||
"next_cursor"
|
||||
],
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"items": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/ReleaseDto"
|
||||
}
|
||||
},
|
||||
"next_cursor": {
|
||||
"type": [
|
||||
"null",
|
||||
"string"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"PageDtoOfSettingDto": {
|
||||
"required": [
|
||||
"items",
|
||||
@@ -6432,6 +6675,27 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"PublishReleaseRequest": {
|
||||
"required": [
|
||||
"manifest",
|
||||
"signature"
|
||||
],
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"manifest": {
|
||||
"type": [
|
||||
"null",
|
||||
"string"
|
||||
]
|
||||
},
|
||||
"signature": {
|
||||
"type": [
|
||||
"null",
|
||||
"string"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"RawChunkMetaDto": {
|
||||
"required": [
|
||||
"chunk_id",
|
||||
@@ -6573,6 +6837,38 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"ReleaseDto": {
|
||||
"required": [
|
||||
"component",
|
||||
"seq",
|
||||
"tag",
|
||||
"version",
|
||||
"digest"
|
||||
],
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"component": {
|
||||
"type": "string"
|
||||
},
|
||||
"seq": {
|
||||
"pattern": "^-?(?:0|[1-9]\\d*)$",
|
||||
"type": [
|
||||
"integer",
|
||||
"string"
|
||||
],
|
||||
"format": "int64"
|
||||
},
|
||||
"tag": {
|
||||
"type": "string"
|
||||
},
|
||||
"version": {
|
||||
"type": "string"
|
||||
},
|
||||
"digest": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"ScoreDto": {
|
||||
"required": [
|
||||
"score",
|
||||
|
||||
@@ -31,6 +31,7 @@ public sealed class ProbeApp : IDisposable
|
||||
_env = new ConnectionEnv(identity, file.ProbeId, file.Limits, directory, new MonoClock(time), time, log);
|
||||
directory.Changed += () => _changed.Release();
|
||||
|
||||
var update = new UpdateBridge(configDirectory, new ConfigStore(configDirectory).Write, log);
|
||||
var options = new FleetLinkOptions
|
||||
{
|
||||
Server = new Uri(file.Server),
|
||||
@@ -38,6 +39,7 @@ public sealed class ProbeApp : IDisposable
|
||||
NodeId = new NodeId(file.ProbeId),
|
||||
NodeVersion = Version,
|
||||
Capabilities = [MonitorCapabilities.Base],
|
||||
HeartbeatExtra = () => JsonSerializer.SerializeToElement(new ProbeHeartbeatExtra { Update = update.ReadStatus() }, MonitorJsonContext.Default.ProbeHeartbeatExtra),
|
||||
HelloMeta = () => JsonSerializer.SerializeToElement(new ProbeHelloMeta { Platform = PlatformDetector.Detect() }, MonitorJsonContext.Default.ProbeHelloMeta),
|
||||
};
|
||||
var list = new StateHandler<ProbeAgentList>(
|
||||
@@ -48,7 +50,18 @@ public sealed class ProbeApp : IDisposable
|
||||
directory.Apply(doc);
|
||||
return ValueTask.FromResult(new StateSyncResult { AppliedVersion = version });
|
||||
});
|
||||
_link = new FleetLink(options, new RpcRouter<LinkContext>(), [list], new Outbox(1 << 20), time, log);
|
||||
var router = new RpcRouter<LinkContext>()
|
||||
.OnNotify(MonitorMethods.UpdateOffer, MonitorJsonContext.Default.UpdateOfferParams, (_, offer, _) =>
|
||||
{
|
||||
update.WriteOffer(offer);
|
||||
return ValueTask.CompletedTask;
|
||||
})
|
||||
.OnNotify(MonitorMethods.UpdateApply, MonitorJsonContext.Default.UpdateOfferParams, (_, _, _) =>
|
||||
{
|
||||
update.RequestApply();
|
||||
return ValueTask.CompletedTask;
|
||||
});
|
||||
_link = new FleetLink(options, router, [list], new Outbox(1 << 20), time, log);
|
||||
}
|
||||
|
||||
/// <summary>到面板的连接（测试和状态查看用）。</summary>
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
using System.Text;
|
||||
using System.Text.Json;
|
||||
using Fleet.Core;
|
||||
using Monitor.Protocol;
|
||||
|
||||
namespace Monitor.Measurement;
|
||||
|
||||
/// <summary>
|
||||
/// 节点进程和宿主机更新器之间的文件交换（容器里 <c>/etc/monitor</c>，也就是数据目录）：
|
||||
/// 节点把面板发来的清单和签名写进 <c>update/</c>，把「更新」请求写成 <c>update/apply.request</c>；更新器验签并更新，状态写在 root 拥有的 <c>update-status/status.json</c>。
|
||||
/// 节点进程不执行任何命令，也不信任清单的内容（验签在宿主机上）。没有安装更新器时目录写不了或没人读，调用只是返回 false。
|
||||
/// </summary>
|
||||
public sealed class UpdateBridge
|
||||
{
|
||||
private const int MaxManifestBytes = 4096;
|
||||
private const int MaxSignatureBytes = 512;
|
||||
private const int MaxStatusBytes = 4096;
|
||||
|
||||
private readonly string _updateDirectory;
|
||||
private readonly string _statusFile;
|
||||
private readonly Action<string, byte[]> _write;
|
||||
private readonly INodeLog _log;
|
||||
|
||||
/// <param name="write">写数据目录里的文件（相对路径，原子替换）：由节点传入 <c>ConfigStore.Write</c>——常驻进程里只有它可以写文件。</param>
|
||||
public UpdateBridge(string dataDirectory, Action<string, byte[]> write, INodeLog log)
|
||||
{
|
||||
_updateDirectory = Path.Combine(dataDirectory, "update");
|
||||
_statusFile = Path.Combine(dataDirectory, "update-status", "status.json");
|
||||
_write = write;
|
||||
_log = log;
|
||||
}
|
||||
|
||||
/// <summary>放下面板发来的清单和签名（和已有的一样就不动，免得每次重连都惊动更新器）。先写清单、后写签名：更新器监视的是签名文件。</summary>
|
||||
public bool WriteOffer(UpdateOfferParams offer)
|
||||
{
|
||||
byte[] manifest = Encoding.UTF8.GetBytes(offer.Manifest);
|
||||
byte[] signature = Encoding.UTF8.GetBytes(offer.Signature);
|
||||
if (manifest.Length is 0 or > MaxManifestBytes || signature.Length is 0 or > MaxSignatureBytes)
|
||||
{
|
||||
_log.Warn("ignoring an update offer of an unexpected size");
|
||||
return false;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
string manifestPath = Path.Combine(_updateDirectory, "offer.manifest");
|
||||
string signaturePath = Path.Combine(_updateDirectory, "offer.sig");
|
||||
if (Same(manifestPath, manifest) && Same(signaturePath, signature))
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
_write("update/offer.manifest", manifest);
|
||||
_write("update/offer.sig", signature);
|
||||
_log.Info("update offer received");
|
||||
return true;
|
||||
}
|
||||
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
|
||||
{
|
||||
_log.Warn("could not store the update offer (is the updater installed?)", ("err", ex.Message));
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>请求更新：写一个空的 <c>apply.request</c>（更新器验签通过、清单更新才会真的动手）。</summary>
|
||||
public bool RequestApply()
|
||||
{
|
||||
try
|
||||
{
|
||||
_write("update/apply.request", []);
|
||||
_log.Info("update requested");
|
||||
return true;
|
||||
}
|
||||
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
|
||||
{
|
||||
_log.Warn("could not request the update (is the updater installed?)", ("err", ex.Message));
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>更新器的状态；没有安装更新器、文件不存在或内容不对时返回 null。</summary>
|
||||
public UpdateStatus? ReadStatus()
|
||||
{
|
||||
try
|
||||
{
|
||||
if (!File.Exists(_statusFile) || new FileInfo(_statusFile).Length > MaxStatusBytes)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
return JsonSerializer.Deserialize(File.ReadAllBytes(_statusFile), MonitorJsonContext.Default.UpdateStatus);
|
||||
}
|
||||
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or JsonException)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
private static bool Same(string path, byte[] content) => File.Exists(path) && File.ReadAllBytes(path).AsSpan().SequenceEqual(content);
|
||||
}
|
||||
@@ -13,6 +13,8 @@ public static class MonitorMethods
|
||||
public const string TestStatus = "monitor.test.status";
|
||||
public const string Event = "monitor.event";
|
||||
public const string Host = "monitor.host";
|
||||
public const string UpdateOffer = "monitor.update.offer";
|
||||
public const string UpdateApply = "monitor.update.apply";
|
||||
|
||||
// Probe ↔ Agent（点对点会话）
|
||||
public const string Clock = "monitor.clock";
|
||||
@@ -217,6 +219,66 @@ public sealed class PlatformInfo
|
||||
public string? BuiltAt { get; set; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 面板给节点的更新清单（<c>monitor.update.offer</c>）：<c>manifest</c> 是发布清单的原始文本，<c>signature</c> 是 base64 的签名。
|
||||
/// 节点只是把它们原样放进数据目录；验签、拉取、重启都由宿主机上的更新器完成（节点进程不执行任何命令，也不信任清单的内容）。
|
||||
/// </summary>
|
||||
public sealed class UpdateOfferParams
|
||||
{
|
||||
[JsonPropertyName("manifest")]
|
||||
public string Manifest { get; set; } = "";
|
||||
|
||||
[JsonPropertyName("signature")]
|
||||
public string Signature { get; set; } = "";
|
||||
}
|
||||
|
||||
/// <summary>宿主机更新器已经验证过的可用更新。</summary>
|
||||
public sealed class UpdateAvailable
|
||||
{
|
||||
[JsonPropertyName("version")]
|
||||
public string? Version { get; set; }
|
||||
|
||||
[JsonPropertyName("tag")]
|
||||
public string? Tag { get; set; }
|
||||
|
||||
[JsonPropertyName("digest")]
|
||||
public string? Digest { get; set; }
|
||||
|
||||
[JsonPropertyName("seq")]
|
||||
public long Seq { get; set; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 宿主机更新器的状态（它写在 <c>update-status/status.json</c>，节点读出来随心跳上报）：
|
||||
/// <c>up_to_date</c>、<c>available</c>、<c>applying</c>、<c>failed</c>、<c>rolled_back</c>、<c>invalid</c>（清单验签或校验没过）。
|
||||
/// 没有安装更新器的节点没有这个字段。
|
||||
/// </summary>
|
||||
public sealed class UpdateStatus
|
||||
{
|
||||
[JsonPropertyName("state")]
|
||||
public string State { get; set; } = "";
|
||||
|
||||
/// <summary>正在运行的镜像 digest（更新器记录的；还没更新过时为空）。</summary>
|
||||
[JsonPropertyName("current")]
|
||||
public string? Current { get; set; }
|
||||
|
||||
[JsonPropertyName("available")]
|
||||
public UpdateAvailable? Available { get; set; }
|
||||
|
||||
[JsonPropertyName("error")]
|
||||
public string? Error { get; set; }
|
||||
|
||||
[JsonPropertyName("at")]
|
||||
public long At { get; set; }
|
||||
}
|
||||
|
||||
/// <summary>Probe 的 <c>fleet.heartbeat</c> 附加字段：更新器的状态。</summary>
|
||||
public sealed class ProbeHeartbeatExtra
|
||||
{
|
||||
[JsonPropertyName("update")]
|
||||
public UpdateStatus? Update { get; set; }
|
||||
}
|
||||
|
||||
/// <summary>Probe 的 <c>fleet.hello</c> 附加字段：系统、架构和构建信息（只用于展示和更新）。</summary>
|
||||
public sealed class ProbeHelloMeta
|
||||
{
|
||||
@@ -326,6 +388,9 @@ public sealed class AgentHeartbeatExtra
|
||||
|
||||
[JsonPropertyName("queue_bytes")]
|
||||
public long QueueBytes { get; set; }
|
||||
|
||||
[JsonPropertyName("update")]
|
||||
public UpdateStatus? Update { get; set; }
|
||||
}
|
||||
|
||||
/// <summary>Agent 下发给 Probe 的一条线路任务（期望状态类型 <c>line_task_set</c> 里的一项）。</summary>
|
||||
@@ -465,6 +530,9 @@ public static class FragmentKeys
|
||||
[JsonSerializable(typeof(TestStatusParams))]
|
||||
[JsonSerializable(typeof(AgentEventParams))]
|
||||
[JsonSerializable(typeof(ProbeAgentList))]
|
||||
[JsonSerializable(typeof(UpdateOfferParams))]
|
||||
[JsonSerializable(typeof(UpdateStatus))]
|
||||
[JsonSerializable(typeof(ProbeHeartbeatExtra))]
|
||||
[JsonSerializable(typeof(ProbeHelloMeta))]
|
||||
[JsonSerializable(typeof(AgentEnrollMeta))]
|
||||
[JsonSerializable(typeof(PlatformInfo))]
|
||||
|
||||
@@ -1,11 +1,13 @@
|
||||
using Fleet.Core;
|
||||
using Microsoft.AspNetCore.Builder;
|
||||
using Microsoft.AspNetCore.Http;
|
||||
using Microsoft.AspNetCore.Routing;
|
||||
using Monitor.Backend.Application;
|
||||
using Monitor.Protocol;
|
||||
|
||||
namespace Monitor.Backend.Api;
|
||||
|
||||
/// <summary>管理端的构建信息：后端自己和每个 Agent、Probe 的版本、tag、提交、构建时间（节点上报的，不含任何地址）。</summary>
|
||||
/// <summary>构建信息与更新：后端和每个节点的版本、tag、构建时间，CI 签名的发布清单，以及「更新这个节点」的请求。更新本身由节点宿主机上的更新器验签并执行。</summary>
|
||||
public static class BuildEndpoints
|
||||
{
|
||||
private const string Tag = "admin-build";
|
||||
@@ -13,18 +15,44 @@ public static class BuildEndpoints
|
||||
public static void Map(RouteGroupBuilder group)
|
||||
{
|
||||
group.MapGet("/build-info", GetAsync)
|
||||
.Api("build_info_get", "Version, tag, commit and build time of the backend and every agent and probe", Tag)
|
||||
.Api("build_info_get", "Version, tag, commit, build time and update state of the backend and every agent and probe", Tag)
|
||||
.Returns<BuildInfoDto>().ProducesProblems(401, 403);
|
||||
group.MapGet("/releases", ListReleasesAsync)
|
||||
.Api("releases_list", "The latest signed release manifest of each component", Tag).Returns<PageDto<ReleaseDto>>().ProducesProblems(401, 403);
|
||||
group.MapPost("/releases", PublishReleaseAsync)
|
||||
.Api("releases_publish", "Register a CI-signed release manifest; online nodes get it right away (their updaters verify the signature)", Tag)
|
||||
.Returns<ReleaseDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403, 409);
|
||||
group.MapPost("/nodes/{id}/update", RequestUpdateAsync)
|
||||
.Api("nodes_update", "Ask an online agent or probe to install the release it has been offered", Tag).Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403, 409);
|
||||
}
|
||||
|
||||
private static async Task<IResult> GetAsync(HttpContext http, NodeInfoService nodes, CancellationToken ct)
|
||||
private static async Task<IResult> GetAsync(HttpContext http, NodeInfoService nodes, ReleaseService releases, CancellationToken ct)
|
||||
{
|
||||
var items = (await nodes.ListAsync(ct))
|
||||
.OrderBy(n => n.Kind, StringComparer.Ordinal)
|
||||
.ThenBy(n => n.NodeId, StringComparer.Ordinal)
|
||||
.Select(n => new NodeBuildDto(n.NodeId, n.Kind, n.Os, n.OsName, n.Arch, n.Version, n.Tag, n.Commit, n.BuiltAt))
|
||||
.Select(n => new NodeBuildDto(n.NodeId, n.Kind, n.Os, n.OsName, n.Arch, n.Version, n.Tag, n.Commit, n.BuiltAt, ToDto(releases.StatusOf(new NodeId(n.NodeId)))))
|
||||
.ToList();
|
||||
http.Response.Headers.CacheControl = "no-store";
|
||||
return TypedResults.Json(new BuildInfoDto(NodeEndpoints.Backend(withCommit: true), items), ApiJsonContext.Default.BuildInfoDto);
|
||||
}
|
||||
|
||||
private static async Task<IResult> ListReleasesAsync(ReleaseService releases, CancellationToken ct) =>
|
||||
TypedResults.Json(new PageDto<ReleaseDto>([.. (await releases.ListAsync(ct)).Select(ToDto)], null), ApiJsonContext.Default.PageDtoReleaseDto);
|
||||
|
||||
private static async Task<IResult> PublishReleaseAsync(HttpContext http, ReleaseService releases, PublishReleaseRequest request)
|
||||
{
|
||||
Result<ReleaseOffer> result = await releases.PublishAsync(request.Manifest ?? "", request.Signature ?? "", http.RequestAborted);
|
||||
return result.TryGet(out ReleaseOffer? offer, out FleetError? error)
|
||||
? TypedResults.Json(ToDto(offer), ApiJsonContext.Default.ReleaseDto, statusCode: StatusCodes.Status201Created)
|
||||
: Problems.From(http, error);
|
||||
}
|
||||
|
||||
private static async Task<IResult> RequestUpdateAsync(HttpContext http, ReleaseService releases, string id, CancellationToken ct) =>
|
||||
await releases.RequestUpdateAsync(new NodeId(id), ct) ? TypedResults.NoContent() : Problems.Create(http, MonitorErrors.AgentOffline, "the node is not connected");
|
||||
|
||||
private static ReleaseDto ToDto(ReleaseOffer offer) => new(offer.Component, offer.Seq, offer.Tag, offer.Version, offer.Digest);
|
||||
|
||||
private static NodeUpdateDto? ToDto(UpdateStatus? status) =>
|
||||
status is null ? null : new NodeUpdateDto(status.State, status.Current, status.Available?.Tag, status.Available?.Version, status.Error, status.At > 0 ? DateTimeOffset.FromUnixTimeSeconds(status.At) : null);
|
||||
}
|
||||
@@ -124,6 +124,14 @@ public sealed record ChangePasswordRequest(string Password);
|
||||
public sealed record RecomputeDto(string State, IReadOnlyList<string> Metrics, long WindowsDone, long WindowsTotal, DateTimeOffset? From, DateTimeOffset? To, int QueueLength);
|
||||
|
||||
/// <summary>管理端看的构建信息：每个节点自报的版本、tag、提交和构建时间，以及系统。</summary>
|
||||
public sealed record NodeBuildDto(string Id, string Kind, string? Os, string? OsName, string? Arch, string? Version, string? Tag, string? Commit, string? BuiltAt);
|
||||
public sealed record NodeBuildDto(string Id, string Kind, string? Os, string? OsName, string? Arch, string? Version, string? Tag, string? Commit, string? BuiltAt, NodeUpdateDto? Update = null);
|
||||
|
||||
/// <summary>节点宿主机上的更新器报告的状态（<c>up_to_date</c>、<c>available</c>、<c>applying</c>、<c>failed</c>、<c>rolled_back</c>、<c>invalid</c>）；没装更新器的节点没有这个字段。</summary>
|
||||
public sealed record NodeUpdateDto(string State, string? CurrentDigest, string? AvailableTag, string? AvailableVersion, string? Error, DateTimeOffset? At);
|
||||
|
||||
/// <summary>面板登记的最新发布清单（CI 签名的；验签在节点上）。</summary>
|
||||
public sealed record ReleaseDto(string Component, long Seq, string Tag, string Version, string Digest);
|
||||
|
||||
public sealed record PublishReleaseRequest(string? Manifest, string? Signature);
|
||||
|
||||
public sealed record BuildInfoDto(BuildDto Backend, IReadOnlyList<NodeBuildDto> Nodes);
|
||||
@@ -38,6 +38,9 @@ namespace Monitor.Backend.Api;
|
||||
[JsonSerializable(typeof(PageDto<AgentDto>))]
|
||||
[JsonSerializable(typeof(AgentPatchRequest))]
|
||||
[JsonSerializable(typeof(BuildDto))]
|
||||
[JsonSerializable(typeof(ReleaseDto))]
|
||||
[JsonSerializable(typeof(PageDto<ReleaseDto>))]
|
||||
[JsonSerializable(typeof(PublishReleaseRequest))]
|
||||
[JsonSerializable(typeof(AboutDto))]
|
||||
[JsonSerializable(typeof(NodeBuildDto))]
|
||||
[JsonSerializable(typeof(BuildInfoDto))]
|
||||
|
||||
@@ -52,9 +52,11 @@ public sealed class MonitorNodeEventSink : INodeEventSink
|
||||
private readonly LiveHub _live;
|
||||
private readonly AgentService _service;
|
||||
private readonly NodeInfoService _nodes;
|
||||
private readonly ReleaseService _releases;
|
||||
|
||||
public MonitorNodeEventSink(IAgentStore agents, AgentRuntime runtime, IEventStore events, LiveHub live, AgentService service, NodeInfoService nodes)
|
||||
public MonitorNodeEventSink(IAgentStore agents, AgentRuntime runtime, IEventStore events, LiveHub live, AgentService service, NodeInfoService nodes, ReleaseService releases)
|
||||
{
|
||||
_releases = releases;
|
||||
_nodes = nodes;
|
||||
_agents = agents;
|
||||
_runtime = runtime;
|
||||
@@ -80,6 +82,7 @@ public sealed class MonitorNodeEventSink : INodeEventSink
|
||||
break;
|
||||
case NodeEventKind.Offline:
|
||||
_runtime.MarkOffline(id);
|
||||
_releases.RecordStatus(id, null);
|
||||
_live.Publish(new NodeSignal("agent", id.Value, false, nodeEvent.AtMs));
|
||||
await _events.AddAsync(id, "agent_offline", nodeEvent.AtMs, null, ct);
|
||||
break;
|
||||
@@ -93,6 +96,7 @@ public sealed class MonitorNodeEventSink : INodeEventSink
|
||||
AgentHeartbeatExtra? beat = extra.Deserialize(MonitorJsonContext.Default.AgentHeartbeatExtra);
|
||||
state.LastHeartbeat = beat;
|
||||
state.LastHeartbeatAtMs = nodeEvent.AtMs;
|
||||
_releases.RecordStatus(id, beat?.Update);
|
||||
if (beat is not null)
|
||||
{
|
||||
state.ReplaceProbes(beat.Probes.Select(p => new ConnectedProbeInfo(p.Id.Value, p.Version, p.Remote, p.SinceUtcMs)));
|
||||
@@ -116,18 +120,37 @@ public sealed class MonitorNodeEventSink : INodeEventSink
|
||||
{
|
||||
switch (nodeEvent.Kind)
|
||||
{
|
||||
case NodeEventKind.Online or NodeEventKind.Offline:
|
||||
_live.Publish(new NodeSignal("probe", id.Value, nodeEvent.Kind == NodeEventKind.Online, nodeEvent.AtMs));
|
||||
case NodeEventKind.Online:
|
||||
_live.Publish(new NodeSignal("probe", id.Value, true, nodeEvent.AtMs));
|
||||
break;
|
||||
case NodeEventKind.Hello when nodeEvent.Hello?.Meta is { } raw:
|
||||
case NodeEventKind.Hello:
|
||||
if (nodeEvent.Hello?.Meta is { } raw)
|
||||
{
|
||||
try
|
||||
{
|
||||
ProbeHelloMeta? meta = raw.Deserialize(MonitorJsonContext.Default.ProbeHelloMeta);
|
||||
await _nodes.SetPlatformAsync(id.Value, NodeKinds.Probe, meta?.Platform, ct);
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
// 格式不对就忽略
|
||||
}
|
||||
}
|
||||
|
||||
await _releases.OfferToNodeAsync(id, ct);
|
||||
break;
|
||||
case NodeEventKind.Offline:
|
||||
_live.Publish(new NodeSignal("probe", id.Value, false, nodeEvent.AtMs));
|
||||
_releases.RecordStatus(id, null);
|
||||
break;
|
||||
case NodeEventKind.Heartbeat when nodeEvent.Extra is { } extra:
|
||||
try
|
||||
{
|
||||
ProbeHelloMeta? meta = raw.Deserialize(MonitorJsonContext.Default.ProbeHelloMeta);
|
||||
await _nodes.SetPlatformAsync(id.Value, NodeKinds.Probe, meta?.Platform, ct);
|
||||
_releases.RecordStatus(id, extra.Deserialize(MonitorJsonContext.Default.ProbeHeartbeatExtra)?.Update);
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
// 格式不对就忽略
|
||||
// 忽略格式不正确的附加字段
|
||||
}
|
||||
|
||||
break;
|
||||
@@ -178,6 +201,7 @@ public sealed class MonitorNodeEventSink : INodeEventSink
|
||||
// 端口或证书指纹变了，Probe 需要新的列表
|
||||
AgentRecord? after = await _agents.GetAsync(id, ct);
|
||||
_nodes.ObserveAgentInBackground(id.Value, after?.PublicHost, meta.Platform);
|
||||
await _releases.OfferToNodeAsync(id, ct);
|
||||
if (before is not null && after is not null
|
||||
&& (!before.TlsSpki.AsSpan().SequenceEqual(after.TlsSpki) || before.ProbeTcpPort != after.ProbeTcpPort || !before.ProbeUdpPorts.SequenceEqual(after.ProbeUdpPorts))
|
||||
&& after.Status == NodeStatus.Active)
|
||||
|
||||
@@ -35,6 +35,7 @@ public static class ApplicationServiceCollectionExtensions
|
||||
services.AddSingleton<WindowComputer>();
|
||||
services.AddSingleton<AuthService>();
|
||||
services.AddSingleton<SettingsService>();
|
||||
services.AddSingleton<ReleaseService>();
|
||||
services.AddSingleton<JoinTokenService>();
|
||||
services.AddSingleton<RawBrowserService>();
|
||||
services.AddSingleton<EventService>();
|
||||
|
||||
@@ -10,6 +10,9 @@ public interface IAgentGateway
|
||||
{
|
||||
IReadOnlyCollection<NodeId> OnlineAgents { get; }
|
||||
|
||||
/// <summary>所有在线的节点（Agent 和 Probe）。</summary>
|
||||
IReadOnlyCollection<NodeId> OnlineNodes { get; }
|
||||
|
||||
bool IsOnline(NodeId agent);
|
||||
|
||||
/// <summary>某个 Agent 的期望状态变了：Gateway 重新计算并推送。</summary>
|
||||
@@ -26,4 +29,10 @@ public interface IAgentGateway
|
||||
ValueTask<Result<bool>> DisconnectProbeAsync(NodeId agent, ProbeId probe, CancellationToken ct);
|
||||
|
||||
ValueTask DisconnectAsync(NodeId agent, string reason, CancellationToken ct);
|
||||
|
||||
/// <summary>把发布清单和签名原样交给节点（通知，不等回复）。</summary>
|
||||
ValueTask NotifyUpdateOfferAsync(NodeId node, string manifest, string signature, CancellationToken ct);
|
||||
|
||||
/// <summary>请求节点更新到它手里的清单。节点不在线返回 false。</summary>
|
||||
ValueTask<bool> NotifyUpdateApplyAsync(NodeId node, CancellationToken ct);
|
||||
}
|
||||
@@ -0,0 +1,158 @@
|
||||
using System.Collections.Concurrent;
|
||||
using System.Diagnostics.CodeAnalysis;
|
||||
using System.Text.Json;
|
||||
using System.Text.RegularExpressions;
|
||||
using Fleet.Core;
|
||||
using Monitor.Protocol;
|
||||
|
||||
namespace Monitor.Backend.Application;
|
||||
|
||||
/// <summary>面板记下的、CI 签名的发布清单（只留每个组件最新的一份）。<c>Manifest</c> 是签名对象的原始文本，面板一个字节也不改。</summary>
|
||||
public sealed record ReleaseOffer(string Component, long Seq, string Tag, string Version, string Digest, string Manifest, string Signature);
|
||||
|
||||
/// <summary>
|
||||
/// 发布清单的分发：CI 签名之后推给面板，面板存下来并原样转给在线的 Agent、Probe（节点连上时再补发一次）。
|
||||
/// <b>面板不验签、也不决定拉什么</b>：节点宿主机上的更新器用本机的发布公钥验签，并且只认本机配置的镜像仓库；
|
||||
/// 所以面板即使被攻破，也推不出一个能被装上的假镜像。面板只负责「通知」和「请求更新」，状态由节点随心跳报回来。
|
||||
/// </summary>
|
||||
public sealed partial class ReleaseService
|
||||
{
|
||||
public const int MaxManifestBytes = 4096;
|
||||
public const int MaxSignatureBytes = 512;
|
||||
private static readonly string[] s_components = [NodeKinds.Agent, NodeKinds.Probe];
|
||||
|
||||
private readonly ISettingsStore _settings;
|
||||
private readonly IAgentGateway _gateway;
|
||||
private readonly ConcurrentDictionary<string, UpdateStatus> _status = new();
|
||||
|
||||
public ReleaseService(ISettingsStore settings, IAgentGateway gateway)
|
||||
{
|
||||
_settings = settings;
|
||||
_gateway = gateway;
|
||||
}
|
||||
|
||||
/// <summary>登记一份新清单并推给在线的同类节点。只要格式对、<c>seq</c> 比现有的新就收下（签名由节点验证）。</summary>
|
||||
public async ValueTask<Result<ReleaseOffer>> PublishAsync(string manifest, string signature, CancellationToken ct)
|
||||
{
|
||||
if (!TryParse(manifest, signature, out ReleaseOffer? offer, out string? problem))
|
||||
{
|
||||
return ValidationError.Fail<ReleaseOffer>("manifest", problem);
|
||||
}
|
||||
|
||||
ReleaseOffer? current = await GetAsync(offer.Component, ct);
|
||||
if (current is not null && offer.Seq <= current.Seq)
|
||||
{
|
||||
return Result<ReleaseOffer>.Fail(MonitorErrors.NameConflict, $"a release with seq {current.Seq} or newer is already registered");
|
||||
}
|
||||
|
||||
await _settings.SetAsync(Key(offer.Component, "manifest"), offer.Manifest, ct);
|
||||
await _settings.SetAsync(Key(offer.Component, "signature"), offer.Signature, ct);
|
||||
foreach (NodeId node in OnlineOf(offer.Component))
|
||||
{
|
||||
await _gateway.NotifyUpdateOfferAsync(node, offer.Manifest, offer.Signature, ct);
|
||||
}
|
||||
|
||||
return Result<ReleaseOffer>.Ok(offer);
|
||||
}
|
||||
|
||||
public async ValueTask<ReleaseOffer?> GetAsync(string component, CancellationToken ct)
|
||||
{
|
||||
string? manifest = await _settings.GetAsync(Key(component, "manifest"), ct);
|
||||
string? signature = await _settings.GetAsync(Key(component, "signature"), ct);
|
||||
return manifest is not null && signature is not null && TryParse(manifest, signature, out ReleaseOffer? offer, out _) && offer.Component == component ? offer : null;
|
||||
}
|
||||
|
||||
public async ValueTask<IReadOnlyList<ReleaseOffer>> ListAsync(CancellationToken ct)
|
||||
{
|
||||
var list = new List<ReleaseOffer>();
|
||||
foreach (string component in s_components)
|
||||
{
|
||||
if (await GetAsync(component, ct) is { } offer)
|
||||
{
|
||||
list.Add(offer);
|
||||
}
|
||||
}
|
||||
|
||||
return list;
|
||||
}
|
||||
|
||||
/// <summary>节点刚连上：把它这个组件最新的清单补发一份（节点离线时发布的也不会错过）。</summary>
|
||||
public async ValueTask OfferToNodeAsync(NodeId node, CancellationToken ct)
|
||||
{
|
||||
if (ComponentOf(node) is { } component && await GetAsync(component, ct) is { } offer)
|
||||
{
|
||||
await _gateway.NotifyUpdateOfferAsync(node, offer.Manifest, offer.Signature, ct);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>请求某个节点更新到它手里那份（验过签的）清单。节点不在线返回 false。</summary>
|
||||
public ValueTask<bool> RequestUpdateAsync(NodeId node, CancellationToken ct) => _gateway.NotifyUpdateApplyAsync(node, ct);
|
||||
|
||||
public void RecordStatus(NodeId node, UpdateStatus? status)
|
||||
{
|
||||
if (status is null)
|
||||
{
|
||||
_status.TryRemove(node.Value, out _);
|
||||
}
|
||||
else
|
||||
{
|
||||
_status[node.Value] = status;
|
||||
}
|
||||
}
|
||||
|
||||
public UpdateStatus? StatusOf(NodeId node) => _status.TryGetValue(node.Value, out UpdateStatus? status) ? status : null;
|
||||
|
||||
public void Forget(NodeId node) => _status.TryRemove(node.Value, out _);
|
||||
|
||||
private IEnumerable<NodeId> OnlineOf(string component) => _gateway.OnlineNodes.Where(n => ComponentOf(n) == component);
|
||||
|
||||
private static string? ComponentOf(NodeId node) =>
|
||||
node.Value.StartsWith(AgentIds.Prefix, StringComparison.Ordinal) ? NodeKinds.Agent
|
||||
: node.Value.StartsWith(ProbeId.Prefix, StringComparison.Ordinal) ? NodeKinds.Probe
|
||||
: null;
|
||||
|
||||
private static string Key(string component, string part) => $"release.{component}.{part}";
|
||||
|
||||
private static bool TryParse(string manifest, string signature, [NotNullWhen(true)] out ReleaseOffer? offer, [NotNullWhen(false)] out string? problem)
|
||||
{
|
||||
offer = null;
|
||||
problem = null;
|
||||
if (manifest.Length is 0 or > MaxManifestBytes || signature.Length is 0 or > MaxSignatureBytes || !Base64().IsMatch(signature))
|
||||
{
|
||||
problem = "manifest or signature has an unexpected size or encoding";
|
||||
return false;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
using JsonDocument document = JsonDocument.Parse(manifest);
|
||||
JsonElement root = document.RootElement;
|
||||
string component = Text(root, "component");
|
||||
string digest = Text(root, "digest");
|
||||
if (root.ValueKind != JsonValueKind.Object || Array.IndexOf(s_components, component) < 0
|
||||
|| !root.TryGetProperty("seq", out JsonElement seq) || !seq.TryGetInt64(out long seqValue) || seqValue <= 0
|
||||
|| !Digest().IsMatch(digest) || Text(root, "image").Length is 0 or > 200)
|
||||
{
|
||||
problem = "manifest needs a known component, a positive seq, an image and a sha256 digest";
|
||||
return false;
|
||||
}
|
||||
|
||||
offer = new ReleaseOffer(component, seqValue, Text(root, "tag"), Text(root, "version"), digest, manifest, signature);
|
||||
return true;
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
problem = "manifest is not valid JSON";
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
private static string Text(JsonElement root, string name) =>
|
||||
root.ValueKind == JsonValueKind.Object && root.TryGetProperty(name, out JsonElement value) && value.ValueKind == JsonValueKind.String ? value.GetString() ?? "" : "";
|
||||
|
||||
[GeneratedRegex("^[A-Za-z0-9+/=]+$")]
|
||||
private static partial Regex Base64();
|
||||
|
||||
[GeneratedRegex("^sha256:[0-9a-f]{64}$")]
|
||||
private static partial Regex Digest();
|
||||
}
|
||||
@@ -26,6 +26,8 @@ public sealed class FleetGateway : IAgentGateway
|
||||
|
||||
public IReadOnlyCollection<NodeId> OnlineAgents => [.. Connections.OnlineNodes.Where(n => n.Value.StartsWith(AgentIds.Prefix, StringComparison.Ordinal))];
|
||||
|
||||
public IReadOnlyCollection<NodeId> OnlineNodes => Connections.OnlineNodes;
|
||||
|
||||
public bool IsOnline(NodeId agent) => Connections.IsOnline(agent);
|
||||
|
||||
public void NotifyTaskSetChanged(NodeId agent) => Notifier.NotifyChanged(agent);
|
||||
@@ -61,4 +63,10 @@ public sealed class FleetGateway : IAgentGateway
|
||||
}
|
||||
|
||||
public ValueTask DisconnectAsync(NodeId agent, string reason, CancellationToken ct) => Connections.DisconnectAsync(agent, reason, ct);
|
||||
|
||||
public async ValueTask NotifyUpdateOfferAsync(NodeId node, string manifest, string signature, CancellationToken ct) =>
|
||||
await Connections.NotifyAsync(node, MonitorMethods.UpdateOffer, new UpdateOfferParams { Manifest = manifest, Signature = signature }, MonitorJsonContext.Default.UpdateOfferParams, ct);
|
||||
|
||||
public async ValueTask<bool> NotifyUpdateApplyAsync(NodeId node, CancellationToken ct) =>
|
||||
await Connections.NotifyAsync(node, MonitorMethods.UpdateApply, new UpdateOfferParams(), MonitorJsonContext.Default.UpdateOfferParams, ct);
|
||||
}
|
||||
@@ -56,7 +56,7 @@ public sealed class AgentHarness : IAsyncDisposable
|
||||
};
|
||||
configure?.Invoke(config);
|
||||
LoadedNodeIdentity identity = LoadedNodeIdentity.Load(directory);
|
||||
var app = new AgentApp(config, identity, TimeProvider.System, new ConsoleNodeLog(TimeProvider.System, Console.Out));
|
||||
var app = new AgentApp(config, identity, directory, TimeProvider.System, new ConsoleNodeLog(TimeProvider.System, Console.Out));
|
||||
var harness = new AgentHarness(backend, directory, identity, app);
|
||||
await app.Ready.WaitAsync(TimeSpan.FromSeconds(10));
|
||||
await BackendFixture.EventuallyAsync(() => Task.FromResult(app.Link.IsConnected), because: "the agent should connect to the backend");
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
using System.Net;
|
||||
using System.Text.Json.Nodes;
|
||||
using Monitor.Protocol;
|
||||
using Monitor.TestSupport;
|
||||
|
||||
namespace Monitor.Backend.Tests;
|
||||
|
||||
[Collection("probe-e2e")]
|
||||
public sealed class UpdateTests
|
||||
{
|
||||
private const string Digest = "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
|
||||
|
||||
private readonly BackendFixture _backend;
|
||||
|
||||
public UpdateTests(BackendFixture backend)
|
||||
{
|
||||
_backend = backend;
|
||||
}
|
||||
|
||||
// 面板不验签（节点宿主机上的更新器验），所以测试里签名随便写一个格式对的
|
||||
private static string Manifest(string component, long seq, string digest = Digest) =>
|
||||
$$"""{"schema":1,"component":"{{component}}","channel":"dev","image":"registry.example/monitor-dev/monitor-{{component}}","digest":"{{digest}}","tag":"dev-{{seq}}","version":"0.1.1","commit":"abc","built_at":"2026-10-06T00:00:00Z","seq":{{seq}}}""";
|
||||
|
||||
private async Task<HttpResponseMessage> PublishAsync(string manifest, string signature = "MEUCIQDc") =>
|
||||
await _backend.Admin.PostAsync("/api/admin/releases", BackendFixture.Json(new JsonObject { ["manifest"] = manifest, ["signature"] = signature }));
|
||||
|
||||
[Fact]
|
||||
public async Task Release_IsForwardedByteForByte_ToOnlineNodesOfThatComponent_AndToNodesThatConnectLater()
|
||||
{
|
||||
long seq = TimeProvider.System.GetUtcNow().ToUnixTimeSeconds() * 1000;
|
||||
await using AgentSimulator online = await _backend.ConnectAgentAsync();
|
||||
string manifest = Manifest("agent", seq);
|
||||
|
||||
using HttpResponseMessage published = await PublishAsync(manifest);
|
||||
Assert.Equal(HttpStatusCode.Created, published.StatusCode);
|
||||
JsonNode release = JsonNode.Parse(await published.Content.ReadAsStringAsync())!;
|
||||
Assert.Equal("agent", release["component"]!.GetValue<string>());
|
||||
Assert.Equal(Digest, release["digest"]!.GetValue<string>());
|
||||
|
||||
await BackendFixture.EventuallyAsync(() => Task.FromResult(online.UpdateOffers.ToArray().Any(o => o.Manifest == manifest && o.Signature == "MEUCIQDc")), because: "the offer reaches online agents unchanged");
|
||||
|
||||
// 之后才连上的节点，hello 之后补发
|
||||
await using AgentSimulator late = await _backend.ConnectAgentAsync();
|
||||
await BackendFixture.EventuallyAsync(() => Task.FromResult(late.UpdateOffers.ToArray().Any(o => o.Manifest == manifest)), because: "a node that connects later still gets the latest offer");
|
||||
|
||||
// 另一个组件（probe）的清单不会发给 Agent
|
||||
using HttpResponseMessage probeRelease = await PublishAsync(Manifest("probe", seq));
|
||||
Assert.Equal(HttpStatusCode.Created, probeRelease.StatusCode);
|
||||
await Task.Delay(300);
|
||||
Assert.DoesNotContain(online.UpdateOffers.ToArray(), o => o.Manifest.Contains("\"component\":\"probe\"", StringComparison.Ordinal));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task Release_Registration_RefusesBadManifests_StaleSeq_AndNeedsAnAdmin()
|
||||
{
|
||||
long seq = TimeProvider.System.GetUtcNow().ToUnixTimeSeconds() * 1000 + 5;
|
||||
Assert.Equal(HttpStatusCode.BadRequest, (await PublishAsync("{not json")).StatusCode);
|
||||
Assert.Equal(HttpStatusCode.BadRequest, (await PublishAsync(Manifest("agent", seq, digest: "sha256:short"))).StatusCode);
|
||||
Assert.Equal(HttpStatusCode.BadRequest, (await PublishAsync(Manifest("backend", seq))).StatusCode);
|
||||
Assert.Equal(HttpStatusCode.BadRequest, (await PublishAsync(Manifest("agent", seq), signature: "not base64!")).StatusCode);
|
||||
|
||||
Assert.Equal(HttpStatusCode.Created, (await PublishAsync(Manifest("agent", seq))).StatusCode);
|
||||
Assert.Equal(HttpStatusCode.Conflict, (await PublishAsync(Manifest("agent", seq))).StatusCode); // 同一个 seq：重放
|
||||
Assert.Equal(HttpStatusCode.Conflict, (await PublishAsync(Manifest("agent", seq - 1))).StatusCode); // 更旧的 seq
|
||||
|
||||
using HttpResponseMessage anonymous = await _backend.Anonymous.PostAsync("/api/admin/releases", BackendFixture.Json(new JsonObject { ["manifest"] = Manifest("agent", seq + 1), ["signature"] = "MEUC" }));
|
||||
Assert.Contains(anonymous.StatusCode, new[] { HttpStatusCode.Unauthorized, HttpStatusCode.Forbidden });
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task UpdateRequest_ReachesTheNode_AndItsReportedStatusShowsInBuildInfo()
|
||||
{
|
||||
await using AgentSimulator agent = await _backend.ConnectAgentAsync();
|
||||
using HttpResponseMessage request = await _backend.Admin.PostAsync($"/api/admin/nodes/{agent.NodeId.Value}/update", null);
|
||||
Assert.Equal(HttpStatusCode.NoContent, request.StatusCode);
|
||||
await BackendFixture.EventuallyAsync(() => Task.FromResult(agent.UpdateApplies == 1));
|
||||
|
||||
// 节点（宿主机更新器）报告状态：面板在构建信息里显示
|
||||
await agent.SendUpdateStatusAsync(new UpdateStatus { State = "available", Available = new UpdateAvailable { Tag = "dev-9", Version = "0.1.1", Digest = Digest, Seq = 9 }, At = TimeProvider.System.GetUtcNow().ToUnixTimeSeconds() });
|
||||
await BackendFixture.EventuallyAsync(async () =>
|
||||
{
|
||||
JsonNode info = await _backend.GetJsonAsync(_backend.Admin, "/api/admin/build-info");
|
||||
JsonNode? node = info["nodes"]!.AsArray().FirstOrDefault(n => n!["id"]!.GetValue<string>() == agent.NodeId.Value);
|
||||
return node?["update"]?["state"]?.GetValue<string>() == "available" && node["update"]!["available_tag"]!.GetValue<string>() == "dev-9";
|
||||
}, because: "the update state comes from the node's heartbeat");
|
||||
|
||||
// 节点离线之后不能请求更新
|
||||
string id = agent.NodeId.Value;
|
||||
await agent.DisposeAsync();
|
||||
await BackendFixture.EventuallyAsync(async () =>
|
||||
{
|
||||
using HttpResponseMessage offline = await _backend.Admin.PostAsync($"/api/admin/nodes/{id}/update", null);
|
||||
return offline.StatusCode == HttpStatusCode.Conflict || offline.StatusCode == HttpStatusCode.NotFound;
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -48,6 +48,13 @@ public sealed class AgentSimulator : IAsyncDisposable
|
||||
|
||||
public ConcurrentQueue<TestRunParams> TestRuns { get; } = new();
|
||||
|
||||
/// <summary>面板发来的发布清单（<c>monitor.update.offer</c>）和更新请求（<c>monitor.update.apply</c>）。</summary>
|
||||
public ConcurrentQueue<UpdateOfferParams> UpdateOffers { get; } = new();
|
||||
|
||||
private int _updateApplies;
|
||||
|
||||
public int UpdateApplies => Volatile.Read(ref _updateApplies);
|
||||
|
||||
public ConcurrentQueue<TestId> TestCancels { get; } = new();
|
||||
|
||||
public IReadOnlyList<RejectedItem> RejectNextState { get; set; } = [];
|
||||
@@ -188,6 +195,13 @@ public sealed class AgentSimulator : IAsyncDisposable
|
||||
new TestStatusParams { TestId = test, Status = status, Phase = phase, ErrorCode = errorCode },
|
||||
MonitorJsonContext.Default.TestStatusParams));
|
||||
|
||||
/// <summary>像节点的更新器报告的那样，随心跳上报更新状态。</summary>
|
||||
public Task SendUpdateStatusAsync(UpdateStatus status) =>
|
||||
SendAsync(RpcMessage.Notification(
|
||||
FleetMethods.Heartbeat,
|
||||
new HeartbeatParams { Extra = JsonSerializer.SerializeToElement(new AgentHeartbeatExtra { Update = status }, MonitorJsonContext.Default.AgentHeartbeatExtra) },
|
||||
FleetRpcContext.Default.HeartbeatParams));
|
||||
|
||||
public async Task<RpcMessage> RequestRawAsync(string method, JsonElement? parameters = null) => await RequestAsync(method, parameters);
|
||||
|
||||
public async Task<TaskSet> WaitForTaskSetAsync(Func<TaskSet, bool> predicate, TimeSpan? timeout = null)
|
||||
@@ -389,6 +403,12 @@ public sealed class AgentSimulator : IAsyncDisposable
|
||||
case FleetMethods.Revoked:
|
||||
Revoked = true;
|
||||
break;
|
||||
case MonitorMethods.UpdateOffer:
|
||||
UpdateOffers.Enqueue(message.Params!.Value.Deserialize(MonitorJsonContext.Default.UpdateOfferParams)!);
|
||||
break;
|
||||
case MonitorMethods.UpdateApply:
|
||||
Interlocked.Increment(ref _updateApplies);
|
||||
break;
|
||||
case MonitorMethods.TestRun:
|
||||
TestRunParams run = message.Params!.Value.Deserialize(MonitorJsonContext.Default.TestRunParams)!;
|
||||
TestRuns.Enqueue(run);
|
||||
|
||||
+13
-1
@@ -68,7 +68,7 @@ done
|
||||
for tag in latest "$dev_tag"; do
|
||||
pushed=false
|
||||
for attempt in 1 2 3; do
|
||||
if buildah push --tls-verify=true "$local_image" "docker://$repository:$tag"; then
|
||||
if buildah push --tls-verify=true --digestfile "$work/$component.digest" "$local_image" "docker://$repository:$tag"; then
|
||||
pushed=true
|
||||
break
|
||||
fi
|
||||
@@ -80,3 +80,15 @@ for tag in latest "$dev_tag"; do
|
||||
[[ "$pushed" == true ]] || { echo "could not push $repository:$tag after 3 attempts" >&2; exit 1; }
|
||||
echo "pushed development image $repository:$tag"
|
||||
done
|
||||
|
||||
# 发布清单：给镜像的 digest 签名（私钥只在 CI 密钥里），再登记到面板；面板把它原样转给在线的节点，节点宿主机上的更新器用本机的公钥验签后才会更新。
|
||||
# 没有配置签名密钥（例如 fork）就只构建镜像、不发清单。
|
||||
if [[ -n "${RELEASE_SIGNING_KEY:-}" ]]; then
|
||||
digest="$(cat "$work/$component.digest")"
|
||||
release_dir="$work/$component-release"
|
||||
bash "$root/ci/release-manifest.sh" "$component" "$repository" "$digest" "$dev_tag" dev "$release_dir"
|
||||
if [[ -n "${RELEASE_API_URL:-}" && -n "${RELEASE_API_TOKEN:-}" ]]; then
|
||||
python3 -c 'import json,sys; print(json.dumps({"manifest": open(sys.argv[1]).read(), "signature": open(sys.argv[2]).read()}))' "$release_dir/manifest.json" "$release_dir/manifest.sig" | curl --fail-with-body --silent --show-error --retry 3 -X POST "${RELEASE_API_URL%/}/api/admin/releases" -H "Authorization: Bearer $RELEASE_API_TOKEN" -H 'Content-Type: application/json' --data-binary @- >/dev/null
|
||||
echo "registered the signed $component release with the panel"
|
||||
fi
|
||||
fi
|
||||
@@ -0,0 +1,30 @@
|
||||
#!/usr/bin/env bash
|
||||
# 生成并签名一个镜像的发布清单：ci/release-manifest.sh <组件> <镜像仓库> <digest> <tag> <通道> <输出目录>
|
||||
# 签名私钥从环境变量 RELEASE_SIGNING_KEY（PEM 内容）读取，只写进一个 600 权限的临时文件，用完即删；私钥只放在 CI 密钥里，不进仓库、不上传面板。
|
||||
# 输出：<输出目录>/manifest.json（扁平 JSON，签名对象是它的原始字节）和 manifest.sig（base64 的 DER ECDSA 签名）。
|
||||
set -euo pipefail
|
||||
|
||||
component="${1:?usage: release-manifest.sh <component> <repository> <digest> <tag> <channel> <outdir>}"
|
||||
repository="${2:?}"; digest="${3:?}"; tag="${4:?}"; channel="${5:?}"; outdir="${6:?}"
|
||||
[[ "$component" =~ ^(agent|probe|backend)$ ]] || { echo "unsupported component: $component" >&2; exit 2; }
|
||||
[[ "$digest" =~ ^sha256:[0-9a-f]{64}$ ]] || { echo "digest must look like sha256:<64 hex>" >&2; exit 2; }
|
||||
[[ "$repository" =~ ^[a-z0-9./_-]+$ && "$tag" =~ ^[A-Za-z0-9._-]+$ && "$channel" =~ ^[a-z0-9._-]+$ ]] || { echo "unexpected characters in repository, tag or channel" >&2; exit 2; }
|
||||
[[ -n "${RELEASE_SIGNING_KEY:-}" ]] || { echo "RELEASE_SIGNING_KEY is required" >&2; exit 2; }
|
||||
|
||||
root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
version="$(sed -n 's#.*<Version>\(.*\)</Version>.*#\1#p' "$root/backend/Directory.Build.props" | head -1)"
|
||||
commit="$(git -C "$root" rev-parse --short=10 HEAD 2>/dev/null || true)"
|
||||
built_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
|
||||
seq="$(date +%s)"
|
||||
|
||||
mkdir -p "$outdir"
|
||||
printf '{"schema":1,"component":"%s","channel":"%s","image":"%s","digest":"%s","tag":"%s","version":"%s","commit":"%s","built_at":"%s","seq":%s}' \
|
||||
"$component" "$channel" "$repository" "$digest" "$tag" "$version" "$commit" "$built_at" "$seq" > "$outdir/manifest.json"
|
||||
|
||||
key="$(mktemp)"
|
||||
trap 'rm -f "$key" "$outdir/manifest.sig.bin"' EXIT
|
||||
chmod 600 "$key"
|
||||
printf '%s\n' "$RELEASE_SIGNING_KEY" > "$key"
|
||||
openssl dgst -sha256 -sign "$key" -out "$outdir/manifest.sig.bin" "$outdir/manifest.json"
|
||||
base64 -w0 "$outdir/manifest.sig.bin" > "$outdir/manifest.sig" 2>/dev/null || base64 "$outdir/manifest.sig.bin" | tr -d '\n' > "$outdir/manifest.sig"
|
||||
echo "signed $component $tag ($digest) seq=$seq"
|
||||
+3
-1
@@ -135,7 +135,9 @@
|
||||
| POST | `/api/admin/releases/{app}/{channel}/rollout` | `{version, batches:[{labels?, count?}], soak_minutes}`：分批灰度；只能选择已经签名的清单 |
|
||||
| POST | `/api/admin/releases/{app}/approve` | 对 `policy = notify` 的节点批准更新 `{version, agents?}` |
|
||||
| GET/PATCH | `/api/admin/settings` | 站点公开或私有、是否对访客显示构建信息（`site.show_build`）、保留期等 |
|
||||
| GET | `/api/admin/build-info` | 后端和每个 Agent、Probe 的版本、tag、提交、构建时间、系统（管理端「系统 → 版本」） |
|
||||
| GET | `/api/admin/build-info` | 后端和每个 Agent、Probe 的版本、tag、提交、构建时间、系统，以及节点宿主机更新器报告的更新状态（管理端「系统 → 版本」） |
|
||||
| GET/POST | `/api/admin/releases` | CI 签名的发布清单：POST 登记（`{manifest, signature}`，面板不验签、原样转给在线的节点和之后连上的节点），GET 看每个组件最新的一份 |
|
||||
| POST | `/api/admin/nodes/{id}/update` | 请求一个在线的 Agent 或 Probe 更新到它收到的清单（节点不在线返回 409） |
|
||||
| GET/POST/PATCH | `/api/admin/users` | 首次启动时通过命令行或环境变量创建初始管理员 |
|
||||
|
||||
任务的请求体示例：
|
||||
|
||||
+220
-196
@@ -1,196 +1,220 @@
|
||||
# 部署
|
||||
|
||||
节点（Agent、Probe）是单个 NativeAOT 可执行文件，没有运行时依赖，只需要系统的 OpenSSL 3（`libssl.so.3`）。启动时会自检，缺少时第一步就明确报错。
|
||||
|
||||
## 1. 构建与打包
|
||||
|
||||
```text
|
||||
scripts/publish.sh <agent|probe|backend|fleet-enroll> <rid> → backend/artifacts/publish/<project>/<rid>/
|
||||
scripts/package.sh <agent|probe> <rid> → backend/artifacts/packages/monitor-<role>-<version>-<rid>.tar.gz（附 .sha256）
|
||||
```
|
||||
|
||||
构建信息（程序里显示的 tag、提交、构建时间）：`publish.sh` 会用 `git describe --tags --always --dirty`、`git rev-parse` 和当前时间自动设置环境变量 `MONITOR_TAG`、`MONITOR_COMMIT`、`MONITOR_BUILT_AT`，直接用 `dotnet publish` 或 CI 构建时自己设置它们（容器的 Fastlane 构建用同名的 `--build-arg`）；不设置就是空，本地构建照常可重复。版本号取自 `backend/Directory.Build.props` 的 `Version`。前端的信息由 `web/build-info.mjs` 在构建时写入（版本取自 `web/package.json`）。
|
||||
|
||||
| rid | 目标 | 构建方式 |
|
||||
| --- | --- | --- |
|
||||
| `linux-x64`、`linux-arm64` | Debian/Ubuntu glibc 服务器 | Windows CI 主机通过 AotAnywhere 交叉编译 |
|
||||
| `linux-musl-x64`、`linux-musl-arm64` | Alpine、amd64 OpenWrt、aarch64 OpenWrt 路由器 | Windows CI 主机通过 AotAnywhere 交叉编译 |
|
||||
| `osx-x64`、`osx-arm64` | Intel Mac、Apple Silicon | Windows CI 主机通过 AotAnywhere 交叉编译；发布包未做 Developer ID 签名或 Apple 公证 |
|
||||
| `win-x64`、`win-arm64` | Windows x64、ARM64 | Windows CI 主机上的 Visual Studio C++ 工具链 |
|
||||
|
||||
macOS 的 Apple Silicon 产物带临时 ad-hoc 签名，Intel 产物未签名。通过浏览器下载时，macOS Gatekeeper 可能阻止启动；面向普通用户分发前需要 Developer ID 签名和 Apple 公证。MIPS 不在当前目标列表中（见 `project-layout.md`）。
|
||||
|
||||
仓库内的 `scripts/publish.sh` 面向本机目标平台；Woodpecker 的 tag 流水线在 Windows runner 上构建 Agent、Probe 和 `fleet-enroll` 的所有发布目标，Backend OCI 镜像仍在 Linux runner 上构建。
|
||||
|
||||
## Backend 容器
|
||||
|
||||
Backend 使用 OCI 标准镜像，通过 `registry.oeo.one/monitor/monitor-backend:<version>` 分发，支持 `linux/amd64` 和 `linux/arm64`。容器基于 .NET 10 ASP.NET noble-chiseled-extra 运行时镜像，以非 root 用户运行，在 `8080/tcp` 提供 HTTP 服务；数据库和原始数据统一写入 `/data`。`extra` 变体带 IANA 时区数据，供按时区查询使用。将 `/data` 挂载为持久卷，并在反向代理处配置 HTTPS。
|
||||
|
||||
在部署目录保存此仓库的 `compose.yaml`，先通过部署平台的环境变量或密钥管理设置 `MONITOR_ADMIN_PASSWORD`（可选设置 `MONITOR_ADMIN_USER`、`MONITOR_VERSION`），然后启动：
|
||||
|
||||
```sh
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Compose 将容器端口只绑定到宿主机 `127.0.0.1:8080`，适合由同机 HTTPS 反向代理转发；数据保存在 Docker 命名卷 `monitor-data`。首次启动成功创建管理员后，改密应在管理端完成。
|
||||
|
||||
健康检查端点为 `GET /healthz`。容器定义见 [`../packaging/container/Backend.Containerfile`](../packaging/container/Backend.Containerfile)。
|
||||
|
||||
## 节点二进制发布
|
||||
|
||||
Woodpecker 在 `vMAJOR.MINOR.PATCH` tag 上，由 Windows runner 使用 AotAnywhere 并行构建 Agent/Probe 的 Linux glibc、Linux musl、macOS 和 Windows 产物。Agent 包还包含一次性注册工具 `fleet-enroll`。Linux 归档带有安装脚本和 systemd/OpenWrt 单元；Windows 产物为 `.zip`，Linux/macOS 产物为 `.tar.gz`。Linux glibc 的 Agent 与 Probe 二进制还会打包为 OCI 镜像，支持 `linux/amd64` 和 `linux/arm64`；musl、macOS、Windows 仍通过对应平台归档分发。所有平台产物和 OCI 镜像发布成功后，CI 会创建对应的 Gitea Release，并附上压缩包和 SHA-256 校验文件。macOS 产物目前未签名/公证。安装说明见 [`../backend/agent/README.md`](../backend/agent/README.md) 与 [`../backend/probe/README.md`](../backend/probe/README.md)。
|
||||
|
||||
## CI 工作流
|
||||
|
||||
### Pull request 与 dev 验证
|
||||
|
||||
Pull request 和 `dev` push 会运行 Backend tests；通过后，独立的 `web-build` workflow 才会构建前端并检查 CSS。提交信息后缀 `[SKIP TESTS]` 只跳过 Backend tests，前端构建仍会运行。Gitea PR 事件的 `CI_COMMIT_MESSAGE` 是 PR 标题，因此在 PR 中跳过测试时，把后缀写入 PR 标题；普通分支 push 则写在 commit message 中。
|
||||
|
||||
### main 开发镜像
|
||||
|
||||
`main` 上只有提交信息包含 `[CI]` 的 push 才构建镜像。合并 PR 时，请把 `[CI]` 放入 PR 标题或合并提交标题。Backend、Agent、Probe 的 Linux/amd64 镜像会并行构建，并推送到同一个 Zot Registry 下独立的 `monitor-dev/` 仓库：
|
||||
|
||||
| 镜像 | 滚动标签 | 固定提交标签 |
|
||||
| --- | --- | --- |
|
||||
| Backend | `registry.oeo.one/monitor-dev/monitor-backend:latest` | `registry.oeo.one/monitor-dev/monitor-backend:dev-<12位SHA>` |
|
||||
| Agent | `registry.oeo.one/monitor-dev/monitor-agent:latest` | `registry.oeo.one/monitor-dev/monitor-agent:dev-<12位SHA>` |
|
||||
| Probe | `registry.oeo.one/monitor-dev/monitor-probe:latest` | `registry.oeo.one/monitor-dev/monitor-probe:dev-<12位SHA>` |
|
||||
|
||||
Dev 镜像目前仅支持 amd64。它们不创建 Gitea Release，也不修改正式版 `monitor/` 仓库中的标签。普通 main push 不会构建镜像。
|
||||
|
||||
### 正式版发布
|
||||
|
||||
推送匹配项目版本的 `vMAJOR.MINOR.PATCH` tag 会触发完整跨平台构建、正式 OCI 镜像推送和 Gitea Release。正式镜像使用 `registry.oeo.one/monitor/` 路径；Agent、Probe 提供 amd64 与 arm64 多架构标签，稳定版本更新正式仓库自己的 `latest`。这与 `monitor-dev/` 的 dev `latest` 相互独立。
|
||||
|
||||
Agent 和 Probe 镜像分别发布为 `registry.oeo.one/monitor/monitor-agent:<version>` 与 `registry.oeo.one/monitor/monitor-probe:<version>`，包含 amd64、arm64 多架构索引；也可指定 `:<version>-amd64` 或 `:<version>-arm64`。稳定版本同时更新 `latest`。镜像以非 root 用户（UID/GID 1654）运行，默认读取 `/etc/monitor/agent.json` 或 `/etc/monitor/probe.json`。运行容器时挂载对应配置目录；Probe 还会在该目录写入 `agents.json`，因此目录需可由 1654 用户写入。Agent、Probe 需使用宿主网络以保持节点端口和测量流量行为，并按需添加 `NET_RAW` 能力以执行 ICMP 测量：
|
||||
|
||||
```sh
|
||||
docker run -d --name monitor-agent --restart unless-stopped --network host \
|
||||
--cap-add NET_RAW -v "$PWD/agent-config:/etc/monitor" \
|
||||
registry.oeo.one/monitor/monitor-agent:<version>
|
||||
|
||||
docker run -d --name monitor-probe --restart unless-stopped --network host \
|
||||
--cap-add NET_RAW -v "$PWD/probe-config:/etc/monitor" \
|
||||
registry.oeo.one/monitor/monitor-probe:<version>
|
||||
```
|
||||
|
||||
宿主机配置目录应允许 UID/GID 1654 读写；Probe 需要写权限来更新 `agents.json`。也可通过 Docker Compose 配置相同的网络、卷和能力。
|
||||
|
||||
实测体积（`StackTraceSupport=false`、`IlcFoldIdenticalMethodBodies=true`、`OptimizationPreference=Size`）：
|
||||
|
||||
| 程序 | linux-musl-x64 | linux-x64 | win-x64 |
|
||||
| --- | --- | --- | --- |
|
||||
| monitor-probe | 7.7 MB | 7.7 MB | 5.6 MB |
|
||||
| monitor-agent | 8.4 MB | 8.4 MB | 7.3 MB |
|
||||
| fleet-enroll | 6.4 MB | 6.4 MB | — |
|
||||
|
||||
Linux 上比 Windows 大，是因为 .NET 的加密、压缩、网络本机库被静态链接进来。tar.gz 压缩后 Probe 约 3.6 MB。
|
||||
|
||||
## 2. 安装
|
||||
|
||||
解压 tar.gz，在解压目录里运行 `install.sh`（POSIX sh，root 运行；Debian、Ubuntu、Alpine、OpenWrt 都测试过）：
|
||||
|
||||
```sh
|
||||
# Agent（服务器）：注册并启动
|
||||
./install.sh agent --server https://panel.example.com --join <加入令牌> --name hk-1
|
||||
|
||||
# Probe（家宽网络里的机器或 OpenWrt 路由器）：先在面板生成身份（POST /api/admin/probes，只能下载一次）
|
||||
./install.sh probe --probe-json ./probe.json
|
||||
|
||||
./install.sh uninstall agent|probe [--purge] # --purge 同时删除身份（节点需要重新注册）
|
||||
```
|
||||
|
||||
| 位置 | 内容 | 所有者 |
|
||||
| --- | --- | --- |
|
||||
| `/usr/lib/monitor/` | 二进制 | root，0755：采集进程不能改写自己的可执行文件 |
|
||||
| `/etc/monitor/` | `agent.json` 或 `probe.json`、身份（`node.json`、`node.key`、`tls.pfx`）、`agents.json` | `monitor` 用户，0750 |
|
||||
|
||||
安装脚本会：检查 OpenSSL、创建 `monitor` 用户（`useradd`、busybox `adduser`，OpenWrt 没有这些时直接写 `/etc/passwd`）、安装二进制和服务文件；缺少配置时只安装、不启动，并打印下一步。
|
||||
|
||||
### systemd（`packaging/systemd/*.service`）
|
||||
|
||||
以 `monitor` 用户运行，沙箱：`NoNewPrivileges`、`ProtectSystem=strict`、`ProtectHome`、`PrivateTmp/Devices`、`ProtectKernel*`、`RestrictAddressFamilies=AF_INET AF_INET6`、`RestrictNamespaces`、`MemoryDenyWriteExecute`（NativeAOT 不 JIT）、`SystemCallArchitectures=native`，`MemoryMax`（Agent 128 MB、Probe 64 MB）。
|
||||
|
||||
- **Agent** 只保留 `CAP_NET_RAW`（ICMP 目标任务用），`/etc/monitor` 只读；Probe 没有任何 capability，只对 `agents.json` 所在的目录可写。
|
||||
- 监听 1024 以下的端口（例如把数据面放到 443）需要在 drop-in 里加 `AmbientCapabilities=CAP_NET_BIND_SERVICE` 和对应的 `CapabilityBoundingSet`。默认端口是 7443/tcp+udp（Probe 控制通道和 UDP 数据面）、7444/tcp。
|
||||
|
||||
### OpenWrt（`packaging/openwrt/`）
|
||||
|
||||
只支持 Probe（Agent 面向服务器）。`install.sh probe` 安装 `/etc/init.d/monitor-probe`（procd，崩溃自动重启，日志进 logd）并写入 `/lib/upgrade/keep.d/monitor`，sysupgrade 时保留 `/etc/monitor/`。
|
||||
|
||||
OpenWrt 默认不带 OpenSSL：`opkg install libopenssl3`（较新的快照和 24.10 之后用 `apk add libopenssl3`）。闪存很小时注意：二进制 7.7 MB，配置只在 Agent 列表变化时才写。路由器上建议把 `probe.json` 的 `limits.max_test_mbps` 调低。
|
||||
|
||||
## 3. 验证
|
||||
|
||||
`scripts/smoke-linux.sh` 在 Linux 容器里用发布的二进制跑完整链路（后端 → 注册 → Agent → Probe → 数据落库），`MODE=install` 用打包产物和 `install.sh` 安装、以 `monitor` 用户运行。`scripts/smoke-systemd.sh` 在 systemd 容器里验证服务单元。已经验证过：
|
||||
|
||||
- Alpine 3.22（musl）、Debian 12（glibc）：直接运行和 `install.sh` 安装都通；
|
||||
- OpenWrt（官方 rootfs，busybox，无 `install`/`useradd`/`su`）：安装、建用户、卸载、二进制启动和 OpenSSL 自检；
|
||||
- systemd（Debian 12）：两个服务 active，Agent 只有 `CAP_NET_RAW`、Probe 没有 capability，`NoNewPrivs`、seccomp 生效，Agent 无法写 `/etc/monitor`，没有重启和错误日志。
|
||||
|
||||
没有验证的：arm64 构建、真正的 OpenWrt 设备（有 procd 和真实的内存/闪存限制）、跨公网的真实线路。
|
||||
|
||||
实测常驻内存（RSS，回环，默认模板，稳定后）：Linux 上 Probe 约 21 MB、Agent 约 23 MB；Windows 上约 22 MB、25 MB。
|
||||
|
||||
### 跨机器的真实链路（Windows Probe → WSL2 里的 Agent 和 Backend）
|
||||
|
||||
`scripts/smoke-wsl.py` 用 Windows 上的 NativeAOT Probe 连 WSL2 里的 Agent（真实的虚拟网络，两端的单调时钟原点相差约 38 小时），并用 `tc netem` 在 WSL 里注入故障。结果（Probe 的 RTT 基线约 0.4 ms）：
|
||||
|
||||
| 注入 | 期望 | 实测 |
|
||||
| --- | --- | --- |
|
||||
| Agent→Probe 方向 10% 丢包、30 ms ± 5 ms 延迟（egress netem，只匹配 7443/7444） | 丢包在下行，下行抖动变大 | `loss.down` 8.2%、`loss.up` 0；`jitter.down.p95` 8.7 ms、`jitter.up.p95` 0.18 ms；RTT +31 ms；TCP：`tcp.rtt.p99` 1.2 s、`tcp.slow` 28.8%、`tcp.retrans` 5.9%（Agent 一侧内核计数） |
|
||||
| Probe→Agent 方向 10% 丢包、20 ms ± 3 ms 延迟（ingress + ifb） | 丢包在上行 | `loss.up` 9.4%、`loss.down` 0；`jitter.up.p95` 5.2 ms、`jitter.down.p95` 0 |
|
||||
| 8 秒黑洞（tc ingress drop 7443/7444） | UDP 连续丢包 ~80 个；TCP 不丢包，只有几秒的长尾 | UDP 最长连续丢包 80（10 Hz × 8 s）；`tcp.rtt.max` 9.5 s、`tcp.stall_max` 9.6 s |
|
||||
| `hy2_ladder`（10/25/50/100 Mbit/s） | 无丢包 | `train.loss` 0.006%、`train.jitter.p95` 0.64 ms、可持续 100 Mbit/s |
|
||||
| 杀掉 Agent / 杀掉 Probe 再启动 | 自动恢复 | Agent 重启后 2.1 s 恢复在线并重新连上 Probe；Probe 重启后 0.5 s 重新连上 |
|
||||
|
||||
验证中发现并修掉的两个问题：
|
||||
|
||||
- **Probe 重启后，Agent 沿用了上一个会话的记录**：Probe 重启之后序号从 0 开始，Agent 里同一个序号的旧 t2/t3 还在，于是真正的上行丢失被算成了下行丢失（黑洞测试里 `loss.up` 0、`loss.down` 7.4%）。现在新的 Probe 会话开始时 Agent 清空所有流的记录。
|
||||
- **TCP 回显的几秒中断被记成丢包**：Probe 像 UDP 那样等 2 秒就把没有回复的行交出去，TCP 随后才到的回复没有行可以回填，最严重的长尾反而在 RTT 里看不到（黑洞期间 `tcp.rtt.max` 只有 4 ms）。现在 TCP 的行等回复，30 秒仍然没有才当作连接已断（t4 缺失）。
|
||||
|
||||
没有覆盖的：Windows 上的 Agent（需要给 Windows 防火墙加入站规则）、NAT 重绑定。跨公网的线路见下一节。
|
||||
|
||||
### 跨公网的真实线路（广东移动家宽 → 日本 IIJ 的 VPS）
|
||||
|
||||
2026-10-03 在一条真实线路上试跑过：家宽机器（Debian 13，用户态运行，没有公网 IPv4 入站）跑 Probe 和 Backend，VPS（Debian 12，1 核 470 MB，上面本来就跑着 xray、hysteria2、caddy 等服务）跑 Agent。
|
||||
|
||||
```text
|
||||
浏览器 / 本机前端 ──► https://<公网域名> ──隧道（Cloudflare Tunnel 之类）──► 家宽机器: Backend (:29181)
|
||||
家宽机器: Probe ──WSS 到 https://<公网域名>──► Backend（身份、Agent 列表）
|
||||
家宽机器: Probe ──TCP/UDP 7443、TCP 7444──► VPS: Agent
|
||||
VPS: Agent ──WSS 到 https://<公网域名>──► Backend
|
||||
```
|
||||
|
||||
做法和要点：
|
||||
|
||||
- **Backend 通过隧道暴露**：隧道把一个公网域名转到家宽机器的 `29181`；Backend 监听 `http://0.0.0.0:29181`（只写一个监听地址，同时写 `0.0.0.0` 和 `[::]` 会报地址已被占用），家宽路由器的防火墙不放行这个端口，公网只能经隧道进来。Agent 用 `fleet-enroll --server https://<公网域名>` 注册，之后用 WSS 连回 Backend。
|
||||
- **经隧道注册之后，检查 Agent 的 `public_host`**：Backend 看到的来源地址是隧道的出口，不是 VPS 的地址，要改成 VPS 的真实地址，Probe 才连得上。
|
||||
- **Probe 直连面板**：`probe.json` 里的 `server` 就是面板地址（取自 `Monitor__PublicUrl`，没配就用创建它时的请求地址），Probe 用它连面板，Agent 列表由面板下发；先注册还是先创建 Probe 都可以。
|
||||
- **小 VPS 把 `limits.max_total_mbps` 调低**（试跑时用 100）；Agent 常驻约 23 MB，VPS 上原有的服务不受影响，结束后删除 `/opt/…`、停掉进程即可，没有留下任何东西。
|
||||
- 家宽的 IPv6 前缀会在路由器重新拨号（比如停电）后变化，SSH 地址要跟着换；面板走隧道的域名，不受影响。
|
||||
- 本地电脑没有直连 VPS 的路径时，用家宽机器当跳板（`SSH_ASKPASS` + `SSH_ASKPASS_REQUIRE=force`，密码放环境变量，不写进文件）。
|
||||
|
||||
**常驻（开机自启）**：
|
||||
|
||||
- 家宽机器（没有 root 时）：`~/.config/systemd/user/monitor-backend.service` 和 `monitor-probe.service`，`EnvironmentFile` 指向放配置的 `backend.env`，`Restart=always`，`systemctl --user enable --now …`，再用 `sudo loginctl enable-linger <用户>` 让它们不登录也能起来。Probe 的命令行是 `monitor-probe --config <probe.json 路径>`（默认路径是 `/etc/monitor/probe.json`）。
|
||||
- VPS：`/etc/systemd/system/monitor-agent.service`，`Restart=always`，加 `NoNewPrivileges`、`ProtectSystem=strict`、`ReadWritePaths=/opt/monitor`、`ProtectHome`、`PrivateTmp`。这是不走安装脚本的手动方式；正式安装用上面的 `packaging/systemd`。
|
||||
- 日志进 journal：`journalctl -u monitor-agent`、`journalctl --user -u monitor-probe`。重启 Backend 用 `systemctl` 而不是手动再起一个进程，否则会端口冲突。
|
||||
|
||||
**国家和运营商**：Backend 用 Probe、Agent 的来源地址向 IP 归属服务查一次，展示在国旗和运营商图标上（`Monitor__GeoLookupUrl`，缺省 `https://ip.007995.xyz`；留空就不查；这个服务只供公益使用，署名和使用条款由部署的人自己遵守）。Probe、Agent 自己不访问外部服务，所以客户的防火墙审计里不会多出出站连接；Backend 发出去的只有公网 IP（内网地址不发）。
|
||||
|
||||
**从别处看这个面板**：本机跑前端，在页面里把数据源指向这个域名，用 API 令牌访问，Backend 设 `Monitor__CorsOrigins` 放行前端的来源（见 [web/README.md](../web/README.md)）。
|
||||
|
||||
实测（Probe 在广东移动家宽，Agent 在日本 IIJ）：
|
||||
|
||||
| 项目 | 结果 |
|
||||
| --- | --- |
|
||||
| 延迟 p50 / p95 / p99 | 107 / 107 / 114 ms |
|
||||
| 丢包 | 上行 0%，下行 8.1%（`hy2_ladder` 在 10、25、50、100 Mbit/s 四档下的丢包都是 8～10%，与速率无关：随机丢包，不是限速） |
|
||||
| 抖动 p95（上 / 下） | 0.9 / 5.2 ms |
|
||||
| TCP | 重传 1.9%（批量传输时 5.8%），RTT 最大 412 ms |
|
||||
| `reality_session` | 建连成功率 100%，TCP 建连 p95 115 ms，TLS 握手 p95 117 ms，30 秒长连接无重置；4 秒批量传输峰值 133 Mbit/s、中位数 90 Mbit/s（Agent 上限 100） |
|
||||
| 评分 | REALITY 82（含按需测试）、Hy2 42 |
|
||||
| Agent 主机状态 | CPU 1.5%，内存 274 / 493 MB，已运行约 20.5 天 |
|
||||
|
||||
这次试跑发现并修掉的问题：`hy2_ladder` 的阶梯按「块」而不是按「阶段」计算，真实的 Probe 把一个阶段切成几块，4 个阶段出了 7 步（模拟数据不切块，所以之前的测试没有发现）；现在同一阶段的块先合并。
|
||||
# 部署
|
||||
|
||||
节点（Agent、Probe）是单个 NativeAOT 可执行文件，没有运行时依赖，只需要系统的 OpenSSL 3（`libssl.so.3`）。启动时会自检，缺少时第一步就明确报错。
|
||||
|
||||
## 1. 构建与打包
|
||||
|
||||
```text
|
||||
scripts/publish.sh <agent|probe|backend|fleet-enroll> <rid> → backend/artifacts/publish/<project>/<rid>/
|
||||
scripts/package.sh <agent|probe> <rid> → backend/artifacts/packages/monitor-<role>-<version>-<rid>.tar.gz（附 .sha256）
|
||||
```
|
||||
|
||||
构建信息（程序里显示的 tag、提交、构建时间）：`publish.sh` 会用 `git describe --tags --always --dirty`、`git rev-parse` 和当前时间自动设置环境变量 `MONITOR_TAG`、`MONITOR_COMMIT`、`MONITOR_BUILT_AT`，直接用 `dotnet publish` 或 CI 构建时自己设置它们（容器的 Fastlane 构建用同名的 `--build-arg`）；不设置就是空，本地构建照常可重复。版本号取自 `backend/Directory.Build.props` 的 `Version`。前端的信息由 `web/build-info.mjs` 在构建时写入（版本取自 `web/package.json`）。
|
||||
|
||||
| rid | 目标 | 构建方式 |
|
||||
| --- | --- | --- |
|
||||
| `linux-x64`、`linux-arm64` | Debian/Ubuntu glibc 服务器 | Windows CI 主机通过 AotAnywhere 交叉编译 |
|
||||
| `linux-musl-x64`、`linux-musl-arm64` | Alpine、amd64 OpenWrt、aarch64 OpenWrt 路由器 | Windows CI 主机通过 AotAnywhere 交叉编译 |
|
||||
| `osx-x64`、`osx-arm64` | Intel Mac、Apple Silicon | Windows CI 主机通过 AotAnywhere 交叉编译；发布包未做 Developer ID 签名或 Apple 公证 |
|
||||
| `win-x64`、`win-arm64` | Windows x64、ARM64 | Windows CI 主机上的 Visual Studio C++ 工具链 |
|
||||
|
||||
macOS 的 Apple Silicon 产物带临时 ad-hoc 签名，Intel 产物未签名。通过浏览器下载时，macOS Gatekeeper 可能阻止启动；面向普通用户分发前需要 Developer ID 签名和 Apple 公证。MIPS 不在当前目标列表中（见 `project-layout.md`）。
|
||||
|
||||
仓库内的 `scripts/publish.sh` 面向本机目标平台；Woodpecker 的 tag 流水线在 Windows runner 上构建 Agent、Probe 和 `fleet-enroll` 的所有发布目标，Backend OCI 镜像仍在 Linux runner 上构建。
|
||||
|
||||
## Backend 容器
|
||||
|
||||
Backend 使用 OCI 标准镜像，通过 `registry.oeo.one/monitor/monitor-backend:<version>` 分发，支持 `linux/amd64` 和 `linux/arm64`。容器基于 .NET 10 ASP.NET noble-chiseled-extra 运行时镜像，以非 root 用户运行，在 `8080/tcp` 提供 HTTP 服务；数据库和原始数据统一写入 `/data`。`extra` 变体带 IANA 时区数据，供按时区查询使用。将 `/data` 挂载为持久卷，并在反向代理处配置 HTTPS。
|
||||
|
||||
在部署目录保存此仓库的 `compose.yaml`，先通过部署平台的环境变量或密钥管理设置 `MONITOR_ADMIN_PASSWORD`（可选设置 `MONITOR_ADMIN_USER`、`MONITOR_VERSION`），然后启动：
|
||||
|
||||
```sh
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Compose 将容器端口只绑定到宿主机 `127.0.0.1:8080`，适合由同机 HTTPS 反向代理转发；数据保存在 Docker 命名卷 `monitor-data`。首次启动成功创建管理员后，改密应在管理端完成。
|
||||
|
||||
健康检查端点为 `GET /healthz`。容器定义见 [`../packaging/container/Backend.Containerfile`](../packaging/container/Backend.Containerfile)。
|
||||
|
||||
## 节点二进制发布
|
||||
|
||||
Woodpecker 在 `vMAJOR.MINOR.PATCH` tag 上，由 Windows runner 使用 AotAnywhere 并行构建 Agent/Probe 的 Linux glibc、Linux musl、macOS 和 Windows 产物。Agent 包还包含一次性注册工具 `fleet-enroll`。Linux 归档带有安装脚本和 systemd/OpenWrt 单元；Windows 产物为 `.zip`，Linux/macOS 产物为 `.tar.gz`。Linux glibc 的 Agent 与 Probe 二进制还会打包为 OCI 镜像，支持 `linux/amd64` 和 `linux/arm64`；musl、macOS、Windows 仍通过对应平台归档分发。所有平台产物和 OCI 镜像发布成功后，CI 会创建对应的 Gitea Release，并附上压缩包和 SHA-256 校验文件。macOS 产物目前未签名/公证。安装说明见 [`../backend/agent/README.md`](../backend/agent/README.md) 与 [`../backend/probe/README.md`](../backend/probe/README.md)。
|
||||
|
||||
## CI 工作流
|
||||
|
||||
### Pull request 与 dev 验证
|
||||
|
||||
Pull request 和 `dev` push 会运行 Backend tests；通过后，独立的 `web-build` workflow 才会构建前端并检查 CSS。提交信息后缀 `[SKIP TESTS]` 只跳过 Backend tests，前端构建仍会运行。Gitea PR 事件的 `CI_COMMIT_MESSAGE` 是 PR 标题，因此在 PR 中跳过测试时，把后缀写入 PR 标题；普通分支 push 则写在 commit message 中。
|
||||
|
||||
### main 开发镜像
|
||||
|
||||
`main` 上只有提交信息包含 `[CI]` 的 push 才构建镜像。合并 PR 时，请把 `[CI]` 放入 PR 标题或合并提交标题。Backend、Agent、Probe 的 Linux/amd64 镜像会并行构建，并推送到同一个 Zot Registry 下独立的 `monitor-dev/` 仓库：
|
||||
|
||||
| 镜像 | 滚动标签 | 固定提交标签 |
|
||||
| --- | --- | --- |
|
||||
| Backend | `registry.oeo.one/monitor-dev/monitor-backend:latest` | `registry.oeo.one/monitor-dev/monitor-backend:dev-<12位SHA>` |
|
||||
| Agent | `registry.oeo.one/monitor-dev/monitor-agent:latest` | `registry.oeo.one/monitor-dev/monitor-agent:dev-<12位SHA>` |
|
||||
| Probe | `registry.oeo.one/monitor-dev/monitor-probe:latest` | `registry.oeo.one/monitor-dev/monitor-probe:dev-<12位SHA>` |
|
||||
|
||||
Dev 镜像目前仅支持 amd64。它们不创建 Gitea Release，也不修改正式版 `monitor/` 仓库中的标签。普通 main push 不会构建镜像。
|
||||
|
||||
### 正式版发布
|
||||
|
||||
推送匹配项目版本的 `vMAJOR.MINOR.PATCH` tag 会触发完整跨平台构建、正式 OCI 镜像推送和 Gitea Release。正式镜像使用 `registry.oeo.one/monitor/` 路径；Agent、Probe 提供 amd64 与 arm64 多架构标签，稳定版本更新正式仓库自己的 `latest`。这与 `monitor-dev/` 的 dev `latest` 相互独立。
|
||||
|
||||
Agent 和 Probe 镜像分别发布为 `registry.oeo.one/monitor/monitor-agent:<version>` 与 `registry.oeo.one/monitor/monitor-probe:<version>`，包含 amd64、arm64 多架构索引；也可指定 `:<version>-amd64` 或 `:<version>-arm64`。稳定版本同时更新 `latest`。镜像以非 root 用户（UID/GID 1654）运行，默认读取 `/etc/monitor/agent.json` 或 `/etc/monitor/probe.json`。运行容器时挂载对应配置目录；Probe 还会在该目录写入 `agents.json`，因此目录需可由 1654 用户写入。Agent、Probe 需使用宿主网络以保持节点端口和测量流量行为，并按需添加 `NET_RAW` 能力以执行 ICMP 测量：
|
||||
|
||||
```sh
|
||||
docker run -d --name monitor-agent --restart unless-stopped --network host \
|
||||
--cap-add NET_RAW -v "$PWD/agent-config:/etc/monitor" \
|
||||
registry.oeo.one/monitor/monitor-agent:<version>
|
||||
|
||||
docker run -d --name monitor-probe --restart unless-stopped --network host \
|
||||
--cap-add NET_RAW -v "$PWD/probe-config:/etc/monitor" \
|
||||
registry.oeo.one/monitor/monitor-probe:<version>
|
||||
```
|
||||
|
||||
宿主机配置目录应允许 UID/GID 1654 读写；Probe 需要写权限来更新 `agents.json`。也可通过 Docker Compose 配置相同的网络、卷和能力。
|
||||
|
||||
实测体积（`StackTraceSupport=false`、`IlcFoldIdenticalMethodBodies=true`、`OptimizationPreference=Size`）：
|
||||
|
||||
| 程序 | linux-musl-x64 | linux-x64 | win-x64 |
|
||||
| --- | --- | --- | --- |
|
||||
| monitor-probe | 7.7 MB | 7.7 MB | 5.6 MB |
|
||||
| monitor-agent | 8.4 MB | 8.4 MB | 7.3 MB |
|
||||
| fleet-enroll | 6.4 MB | 6.4 MB | — |
|
||||
|
||||
Linux 上比 Windows 大，是因为 .NET 的加密、压缩、网络本机库被静态链接进来。tar.gz 压缩后 Probe 约 3.6 MB。
|
||||
|
||||
## 2. 安装
|
||||
|
||||
解压 tar.gz，在解压目录里运行 `install.sh`（POSIX sh，root 运行；Debian、Ubuntu、Alpine、OpenWrt 都测试过）：
|
||||
|
||||
```sh
|
||||
# Agent（服务器）：注册并启动
|
||||
./install.sh agent --server https://panel.example.com --join <加入令牌> --name hk-1
|
||||
|
||||
# Probe（家宽网络里的机器或 OpenWrt 路由器）：先在面板生成身份（POST /api/admin/probes，只能下载一次）
|
||||
./install.sh probe --probe-json ./probe.json
|
||||
|
||||
./install.sh uninstall agent|probe [--purge] # --purge 同时删除身份（节点需要重新注册）
|
||||
```
|
||||
|
||||
| 位置 | 内容 | 所有者 |
|
||||
| --- | --- | --- |
|
||||
| `/usr/lib/monitor/` | 二进制 | root，0755：采集进程不能改写自己的可执行文件 |
|
||||
| `/etc/monitor/` | `agent.json` 或 `probe.json`、身份（`node.json`、`node.key`、`tls.pfx`）、`agents.json` | `monitor` 用户，0750 |
|
||||
|
||||
安装脚本会：检查 OpenSSL、创建 `monitor` 用户（`useradd`、busybox `adduser`，OpenWrt 没有这些时直接写 `/etc/passwd`）、安装二进制和服务文件；缺少配置时只安装、不启动，并打印下一步。
|
||||
|
||||
### systemd（`packaging/systemd/*.service`）
|
||||
|
||||
以 `monitor` 用户运行，沙箱：`NoNewPrivileges`、`ProtectSystem=strict`、`ProtectHome`、`PrivateTmp/Devices`、`ProtectKernel*`、`RestrictAddressFamilies=AF_INET AF_INET6`、`RestrictNamespaces`、`MemoryDenyWriteExecute`（NativeAOT 不 JIT）、`SystemCallArchitectures=native`，`MemoryMax`（Agent 128 MB、Probe 64 MB）。
|
||||
|
||||
- **Agent** 只保留 `CAP_NET_RAW`（ICMP 目标任务用），`/etc/monitor` 只读；Probe 没有任何 capability，只对 `agents.json` 所在的目录可写。
|
||||
- 监听 1024 以下的端口（例如把数据面放到 443）需要在 drop-in 里加 `AmbientCapabilities=CAP_NET_BIND_SERVICE` 和对应的 `CapabilityBoundingSet`。默认端口是 7443/tcp+udp（Probe 控制通道和 UDP 数据面）、7444/tcp。
|
||||
|
||||
### OpenWrt（`packaging/openwrt/`）
|
||||
|
||||
只支持 Probe（Agent 面向服务器）。`install.sh probe` 安装 `/etc/init.d/monitor-probe`（procd，崩溃自动重启，日志进 logd）并写入 `/lib/upgrade/keep.d/monitor`，sysupgrade 时保留 `/etc/monitor/`。
|
||||
|
||||
OpenWrt 默认不带 OpenSSL：`opkg install libopenssl3`（较新的快照和 24.10 之后用 `apk add libopenssl3`）。闪存很小时注意：二进制 7.7 MB，配置只在 Agent 列表变化时才写。路由器上建议把 `probe.json` 的 `limits.max_test_mbps` 调低。
|
||||
|
||||
## 3. 验证
|
||||
|
||||
`scripts/smoke-linux.sh` 在 Linux 容器里用发布的二进制跑完整链路（后端 → 注册 → Agent → Probe → 数据落库），`MODE=install` 用打包产物和 `install.sh` 安装、以 `monitor` 用户运行。`scripts/smoke-systemd.sh` 在 systemd 容器里验证服务单元。已经验证过：
|
||||
|
||||
- Alpine 3.22（musl）、Debian 12（glibc）：直接运行和 `install.sh` 安装都通；
|
||||
- OpenWrt（官方 rootfs，busybox，无 `install`/`useradd`/`su`）：安装、建用户、卸载、二进制启动和 OpenSSL 自检；
|
||||
- systemd（Debian 12）：两个服务 active，Agent 只有 `CAP_NET_RAW`、Probe 没有 capability，`NoNewPrivs`、seccomp 生效，Agent 无法写 `/etc/monitor`，没有重启和错误日志。
|
||||
|
||||
没有验证的：arm64 构建、真正的 OpenWrt 设备（有 procd 和真实的内存/闪存限制）、跨公网的真实线路。
|
||||
|
||||
实测常驻内存（RSS，回环，默认模板，稳定后）：Linux 上 Probe 约 21 MB、Agent 约 23 MB；Windows 上约 22 MB、25 MB。
|
||||
|
||||
### 跨机器的真实链路（Windows Probe → WSL2 里的 Agent 和 Backend）
|
||||
|
||||
`scripts/smoke-wsl.py` 用 Windows 上的 NativeAOT Probe 连 WSL2 里的 Agent（真实的虚拟网络，两端的单调时钟原点相差约 38 小时），并用 `tc netem` 在 WSL 里注入故障。结果（Probe 的 RTT 基线约 0.4 ms）：
|
||||
|
||||
| 注入 | 期望 | 实测 |
|
||||
| --- | --- | --- |
|
||||
| Agent→Probe 方向 10% 丢包、30 ms ± 5 ms 延迟（egress netem，只匹配 7443/7444） | 丢包在下行，下行抖动变大 | `loss.down` 8.2%、`loss.up` 0；`jitter.down.p95` 8.7 ms、`jitter.up.p95` 0.18 ms；RTT +31 ms；TCP：`tcp.rtt.p99` 1.2 s、`tcp.slow` 28.8%、`tcp.retrans` 5.9%（Agent 一侧内核计数） |
|
||||
| Probe→Agent 方向 10% 丢包、20 ms ± 3 ms 延迟（ingress + ifb） | 丢包在上行 | `loss.up` 9.4%、`loss.down` 0；`jitter.up.p95` 5.2 ms、`jitter.down.p95` 0 |
|
||||
| 8 秒黑洞（tc ingress drop 7443/7444） | UDP 连续丢包 ~80 个；TCP 不丢包，只有几秒的长尾 | UDP 最长连续丢包 80（10 Hz × 8 s）；`tcp.rtt.max` 9.5 s、`tcp.stall_max` 9.6 s |
|
||||
| `hy2_ladder`（10/25/50/100 Mbit/s） | 无丢包 | `train.loss` 0.006%、`train.jitter.p95` 0.64 ms、可持续 100 Mbit/s |
|
||||
| 杀掉 Agent / 杀掉 Probe 再启动 | 自动恢复 | Agent 重启后 2.1 s 恢复在线并重新连上 Probe；Probe 重启后 0.5 s 重新连上 |
|
||||
|
||||
验证中发现并修掉的两个问题：
|
||||
|
||||
- **Probe 重启后，Agent 沿用了上一个会话的记录**：Probe 重启之后序号从 0 开始，Agent 里同一个序号的旧 t2/t3 还在，于是真正的上行丢失被算成了下行丢失（黑洞测试里 `loss.up` 0、`loss.down` 7.4%）。现在新的 Probe 会话开始时 Agent 清空所有流的记录。
|
||||
- **TCP 回显的几秒中断被记成丢包**：Probe 像 UDP 那样等 2 秒就把没有回复的行交出去，TCP 随后才到的回复没有行可以回填，最严重的长尾反而在 RTT 里看不到（黑洞期间 `tcp.rtt.max` 只有 4 ms）。现在 TCP 的行等回复，30 秒仍然没有才当作连接已断（t4 缺失）。
|
||||
|
||||
没有覆盖的：Windows 上的 Agent（需要给 Windows 防火墙加入站规则）、NAT 重绑定。跨公网的线路见下一节。
|
||||
|
||||
### 跨公网的真实线路（广东移动家宽 → 日本 IIJ 的 VPS）
|
||||
|
||||
2026-10-03 在一条真实线路上试跑过：家宽机器（Debian 13，用户态运行，没有公网 IPv4 入站）跑 Probe 和 Backend，VPS（Debian 12，1 核 470 MB，上面本来就跑着 xray、hysteria2、caddy 等服务）跑 Agent。
|
||||
|
||||
```text
|
||||
浏览器 / 本机前端 ──► https://<公网域名> ──隧道（Cloudflare Tunnel 之类）──► 家宽机器: Backend (:29181)
|
||||
家宽机器: Probe ──WSS 到 https://<公网域名>──► Backend（身份、Agent 列表）
|
||||
家宽机器: Probe ──TCP/UDP 7443、TCP 7444──► VPS: Agent
|
||||
VPS: Agent ──WSS 到 https://<公网域名>──► Backend
|
||||
```
|
||||
|
||||
做法和要点：
|
||||
|
||||
- **Backend 通过隧道暴露**：隧道把一个公网域名转到家宽机器的 `29181`；Backend 监听 `http://0.0.0.0:29181`（只写一个监听地址，同时写 `0.0.0.0` 和 `[::]` 会报地址已被占用），家宽路由器的防火墙不放行这个端口，公网只能经隧道进来。Agent 用 `fleet-enroll --server https://<公网域名>` 注册，之后用 WSS 连回 Backend。
|
||||
- **经隧道注册之后，检查 Agent 的 `public_host`**：Backend 看到的来源地址是隧道的出口，不是 VPS 的地址，要改成 VPS 的真实地址，Probe 才连得上。
|
||||
- **Probe 直连面板**：`probe.json` 里的 `server` 就是面板地址（取自 `Monitor__PublicUrl`，没配就用创建它时的请求地址），Probe 用它连面板，Agent 列表由面板下发；先注册还是先创建 Probe 都可以。
|
||||
- **小 VPS 把 `limits.max_total_mbps` 调低**（试跑时用 100）；Agent 常驻约 23 MB，VPS 上原有的服务不受影响，结束后删除 `/opt/…`、停掉进程即可，没有留下任何东西。
|
||||
- 家宽的 IPv6 前缀会在路由器重新拨号（比如停电）后变化，SSH 地址要跟着换；面板走隧道的域名，不受影响。
|
||||
- 本地电脑没有直连 VPS 的路径时，用家宽机器当跳板（`SSH_ASKPASS` + `SSH_ASKPASS_REQUIRE=force`，密码放环境变量，不写进文件）。
|
||||
|
||||
**常驻（开机自启）**：
|
||||
|
||||
- 家宽机器（没有 root 时）：`~/.config/systemd/user/monitor-backend.service` 和 `monitor-probe.service`，`EnvironmentFile` 指向放配置的 `backend.env`，`Restart=always`，`systemctl --user enable --now …`，再用 `sudo loginctl enable-linger <用户>` 让它们不登录也能起来。Probe 的命令行是 `monitor-probe --config <probe.json 路径>`（默认路径是 `/etc/monitor/probe.json`）。
|
||||
- VPS：`/etc/systemd/system/monitor-agent.service`，`Restart=always`，加 `NoNewPrivileges`、`ProtectSystem=strict`、`ReadWritePaths=/opt/monitor`、`ProtectHome`、`PrivateTmp`。这是不走安装脚本的手动方式；正式安装用上面的 `packaging/systemd`。
|
||||
- 日志进 journal：`journalctl -u monitor-agent`、`journalctl --user -u monitor-probe`。重启 Backend 用 `systemctl` 而不是手动再起一个进程，否则会端口冲突。
|
||||
|
||||
**国家和运营商**：Backend 用 Probe、Agent 的来源地址向 IP 归属服务查一次，展示在国旗和运营商图标上（`Monitor__GeoLookupUrl`，缺省 `https://ip.007995.xyz`；留空就不查；这个服务只供公益使用，署名和使用条款由部署的人自己遵守）。Probe、Agent 自己不访问外部服务，所以客户的防火墙审计里不会多出出站连接；Backend 发出去的只有公网 IP（内网地址不发）。
|
||||
|
||||
**从别处看这个面板**：本机跑前端，在页面里把数据源指向这个域名，用 API 令牌访问，Backend 设 `Monitor__CorsOrigins` 放行前端的来源（见 [web/README.md](../web/README.md)）。
|
||||
|
||||
实测（Probe 在广东移动家宽，Agent 在日本 IIJ）：
|
||||
|
||||
| 项目 | 结果 |
|
||||
| --- | --- |
|
||||
| 延迟 p50 / p95 / p99 | 107 / 107 / 114 ms |
|
||||
| 丢包 | 上行 0%，下行 8.1%（`hy2_ladder` 在 10、25、50、100 Mbit/s 四档下的丢包都是 8～10%，与速率无关：随机丢包，不是限速） |
|
||||
| 抖动 p95（上 / 下） | 0.9 / 5.2 ms |
|
||||
| TCP | 重传 1.9%（批量传输时 5.8%），RTT 最大 412 ms |
|
||||
| `reality_session` | 建连成功率 100%，TCP 建连 p95 115 ms，TLS 握手 p95 117 ms，30 秒长连接无重置；4 秒批量传输峰值 133 Mbit/s、中位数 90 Mbit/s（Agent 上限 100） |
|
||||
| 评分 | REALITY 82（含按需测试）、Hy2 42 |
|
||||
| Agent 主机状态 | CPU 1.5%，内存 274 / 493 MB，已运行约 20.5 天 |
|
||||
|
||||
这次试跑发现并修掉的问题：`hy2_ladder` 的阶梯按「块」而不是按「阶段」计算，真实的 Probe 把一个阶段切成几块，4 个阶段出了 7 步（模拟数据不切块，所以之前的测试没有发现）；现在同一阶段的块先合并。␍
|
||||
|
||||
## 容器节点的更新（Agent、Probe）
|
||||
|
||||
面板通知、节点验签、宿主机更新，**面板即使被攻破也装不上假镜像**：
|
||||
|
||||
```text
|
||||
CI 构建并推镜像（Zot）──► ci/release-manifest.sh：对镜像 digest 的清单签名（ECDSA P-256，私钥只在 Woodpecker 密钥 release_signing_key 里）
|
||||
└─ POST /api/admin/releases ──► 面板：只存下并原样转发（不验签）──► 在线的 Agent、Probe（连上时补发）
|
||||
节点进程：只把清单和签名写进数据目录的 update/，不执行任何命令
|
||||
│ systemd.path 监视到 offer.sig
|
||||
▼
|
||||
宿主机 monitor-update（root）：复制到临时目录 → 用本机的发布公钥验签 → 核对组件和镜像仓库 → seq 必须比已安装的大
|
||||
→ status：available / invalid（写进 update-status/，节点随心跳报给面板，管理端「版本」页显示）
|
||||
→ 管理员点「更新」（或本机配置 POLICY=auto）→ podman pull <仓库>@sha256:<digest>（内容寻址，Registry 或链路上换不了）
|
||||
→ 写 IMAGE=… 到 /etc/monitor-update/<组件>.image，重启容器单元；20 秒内没有健康就换回旧镜像（rolled_back）
|
||||
```
|
||||
|
||||
- **安装更新器**（每个容器节点一次，root）：`packaging/update/install-updater.sh agent --data-dir /opt/monitor/etc --image-repo registry.oeo.one/monitor/monitor-agent --unit monitor-agent-container.service [--policy auto] [--authfile <Registry 认证文件>]`。它装好 `monitor-update` 脚本和发布公钥，写 `/etc/monitor-update/<组件>.conf`，启用两个 systemd 路径单元。容器单元要用 `EnvironmentFile=/etc/monitor-update/<组件>.image` 和 `${IMAGE}` 启动容器。
|
||||
- **镜像仓库、服务名、公钥都在本机配置里**，清单里写什么都不会改变拉取哪个仓库；清单被篡改、签名对不上、组件或仓库不符、`seq` 不比已安装的大（重放旧清单），都会被拒绝，状态是 `invalid`。
|
||||
- **业务进程不能改二进制，也不执行命令**：它只能往 `update/` 里放清单和请求；状态在 root 拥有的 `update-status/` 里（只读）。
|
||||
- **CI 的配置**：Woodpecker 密钥 `release_signing_key`（发布私钥，PEM）、`release_api_token`（面板的 API 令牌，管理员权限，用来登记清单）；环境变量 `RELEASE_API_URL`（面板地址）。没有 `release_signing_key` 就只构建镜像、不发清单。
|
||||
- **发布公钥**在 `packaging/update/release-key.pub.pem`；私钥不入库，请离线备份。更换密钥：节点上换新公钥之后再用新私钥发布。
|
||||
- 纯二进制的安装方式（`fleet-updater`、`fleet-release`，见 [fleet/update.md](fleet/update.md)）还没有实现；容器方式优先。
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Fleet：通用更新（Fleet.Update / fleet-updater）
|
||||
|
||||
> **实现状态**：容器节点（Agent、Probe）的更新已经实现，见 [deployment.md](../deployment.md) 的「容器节点的更新」：同样的信任模型（离线发布密钥签名、本机配置公钥和仓库、`seq` 防重放、面板只通知和请求），清单里是镜像 digest，更新器是宿主机上的 `monitor-update`。本文下面描述的纯二进制方案（`Fleet.Update`、`fleet-updater`、`fleet-release`、健康信标）还没有实现。
|
||||
|
||||
## 1. 原则
|
||||
|
||||
- **与产品无关**：`fleet-updater` 通过本地配置声明它管理哪些应用，一台机器上可以同时管理多个产品。
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
#!/bin/sh
|
||||
# 在容器节点的宿主机上安装更新器：
|
||||
# install-updater.sh <agent|probe> --data-dir <挂载到容器 /etc/monitor 的宿主机目录> --image-repo <镜像仓库，不带 tag> --unit <容器的 systemd 单元名>
|
||||
# [--policy auto|manual] [--authfile <拉镜像用的 Registry 认证文件>]
|
||||
# 需要 root、systemd、podman、openssl。做的事：装脚本和发布公钥，写本机配置，装两个 systemd 单元（有新清单就检查，有「更新」请求就更新）。
|
||||
# 容器的单元要从 EnvironmentFile=/etc/monitor-update/<组件>.image 读 IMAGE=…，并用 ${IMAGE} 启动容器（没有这个文件时先写一份当前镜像）。
|
||||
set -eu
|
||||
|
||||
COMPONENT="${1:-}"; shift || true
|
||||
case "$COMPONENT" in agent|probe) ;; *) echo "usage: install-updater.sh <agent|probe> --data-dir D --image-repo R --unit U [--policy auto|manual] [--authfile F]" >&2; exit 2 ;; esac
|
||||
DATA_DIR=""; IMAGE_REPO=""; UNIT=""; POLICY="manual"; AUTHFILE=""
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--data-dir) DATA_DIR="$2"; shift 2 ;;
|
||||
--image-repo) IMAGE_REPO="$2"; shift 2 ;;
|
||||
--unit) UNIT="$2"; shift 2 ;;
|
||||
--policy) POLICY="$2"; shift 2 ;;
|
||||
--authfile) AUTHFILE="$2"; shift 2 ;;
|
||||
*) echo "unknown option: $1" >&2; exit 2 ;;
|
||||
esac
|
||||
done
|
||||
[ -n "$DATA_DIR" ] && [ -n "$IMAGE_REPO" ] && [ -n "$UNIT" ] || { echo "--data-dir, --image-repo and --unit are required" >&2; exit 2; }
|
||||
case "$POLICY" in auto|manual) ;; *) echo "--policy must be auto or manual" >&2; exit 2 ;; esac
|
||||
[ "$(id -u)" -eq 0 ] || { echo "run as root" >&2; exit 1; }
|
||||
|
||||
HERE="$(cd "$(dirname "$0")" && pwd)"
|
||||
install -d -m 755 /etc/monitor-update /var/lib/monitor-update
|
||||
install -m 755 "$HERE/monitor-update.sh" /usr/local/sbin/monitor-update
|
||||
install -m 644 "$HERE/release-key.pub.pem" /etc/monitor-update/release-key.pub.pem
|
||||
|
||||
# 容器用户（UID 1654）能写 update/（放清单和请求）；update-status/ 归 root，业务进程只读
|
||||
install -d -m 755 -o 1654 -g 1654 "$DATA_DIR/update"
|
||||
install -d -m 755 "$DATA_DIR/update-status"
|
||||
|
||||
cat > "/etc/monitor-update/$COMPONENT.conf" <<CONF
|
||||
DATA_DIR=$DATA_DIR
|
||||
IMAGE_REPO=$IMAGE_REPO
|
||||
UNIT=$UNIT
|
||||
PUBKEY=/etc/monitor-update/release-key.pub.pem
|
||||
ENV_FILE=/etc/monitor-update/$COMPONENT.image
|
||||
STATE_DIR=/var/lib/monitor-update
|
||||
POLICY=$POLICY
|
||||
AUTHFILE=$AUTHFILE
|
||||
CONF
|
||||
chmod 644 "/etc/monitor-update/$COMPONENT.conf"
|
||||
|
||||
cat > "/etc/systemd/system/monitor-update-check-$COMPONENT.service" <<UNITFILE
|
||||
[Unit]
|
||||
Description=Check the signed update offer for monitor-$COMPONENT
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/local/sbin/monitor-update check $COMPONENT
|
||||
UNITFILE
|
||||
cat > "/etc/systemd/system/monitor-update-apply-$COMPONENT.service" <<UNITFILE
|
||||
[Unit]
|
||||
Description=Apply the verified update for monitor-$COMPONENT
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
TimeoutStartSec=300
|
||||
ExecStart=/usr/local/sbin/monitor-update apply $COMPONENT
|
||||
UNITFILE
|
||||
cat > "/etc/systemd/system/monitor-update-check-$COMPONENT.path" <<UNITFILE
|
||||
[Unit]
|
||||
Description=Watch for a new update offer for monitor-$COMPONENT
|
||||
|
||||
[Path]
|
||||
PathChanged=$DATA_DIR/update/offer.sig
|
||||
Unit=monitor-update-check-$COMPONENT.service
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
UNITFILE
|
||||
cat > "/etc/systemd/system/monitor-update-apply-$COMPONENT.path" <<UNITFILE
|
||||
[Unit]
|
||||
Description=Watch for an update request for monitor-$COMPONENT
|
||||
|
||||
[Path]
|
||||
PathChanged=$DATA_DIR/update/apply.request
|
||||
Unit=monitor-update-apply-$COMPONENT.service
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
UNITFILE
|
||||
|
||||
systemctl daemon-reload
|
||||
systemctl enable --now "monitor-update-check-$COMPONENT.path" "monitor-update-apply-$COMPONENT.path"
|
||||
echo "updater installed for $COMPONENT (policy: $POLICY)"
|
||||
@@ -0,0 +1,142 @@
|
||||
#!/bin/sh
|
||||
# Monitor 容器节点（Agent、Probe）的宿主机更新器。用法：monitor-update <check|apply> <组件> 组件 = agent 或 probe
|
||||
#
|
||||
# 信任模型（防篡改、防中间人）：
|
||||
# - 只接受用发布私钥签名的清单（ECDSA P-256 / SHA-256，对清单文件的原始字节签名）；公钥放在本机，面板和 Registry 都改不了它。
|
||||
# - 清单里写的是镜像的 digest：拉取时用 repo@sha256:…，内容寻址，Registry 或链路上的人换不出另一个镜像。
|
||||
# - 镜像仓库、组件、服务名都来自本机的配置（/etc/monitor-update/<组件>.conf），清单里写什么都不会改变拉哪个仓库。
|
||||
# - 清单的 seq 必须比已安装的大（防止旧清单被重放回滚）。
|
||||
# - 业务进程（Agent、Probe）只能往数据目录里写「清单」和「请求」文件，更新由这个宿主机脚本完成，业务进程不执行任何命令。
|
||||
set -eu
|
||||
|
||||
CMD="${1:-}"
|
||||
COMPONENT="${2:-}"
|
||||
case "$CMD" in check|apply) ;; *) echo "usage: monitor-update <check|apply> <agent|probe>" >&2; exit 2 ;; esac
|
||||
case "$COMPONENT" in agent|probe) ;; *) echo "component must be agent or probe" >&2; exit 2 ;; esac
|
||||
|
||||
CONF="${MONITOR_UPDATE_CONF_DIR:-/etc/monitor-update}/$COMPONENT.conf"
|
||||
[ -r "$CONF" ] || { echo "missing $CONF" >&2; exit 2; }
|
||||
# 配置：DATA_DIR（容器里 /etc/monitor 对应的宿主机目录）、IMAGE_REPO、UNIT、PUBKEY、POLICY（auto|manual）、AUTHFILE（可选）、
|
||||
# STATE_DIR（已安装版本的记录）、ENV_FILE（容器单元读取的 IMAGE=… 文件）
|
||||
# shellcheck disable=SC1090
|
||||
. "$CONF"
|
||||
: "${DATA_DIR:?}" "${IMAGE_REPO:?}" "${UNIT:?}" "${PUBKEY:?}" "${ENV_FILE:?}"
|
||||
POLICY="${POLICY:-manual}"
|
||||
STATE_DIR="${STATE_DIR:-/var/lib/monitor-update}"
|
||||
# 业务进程（容器里的 Agent、Probe）可写的目录只有 update/：它在里面放 offer.manifest、offer.sig、apply.request。
|
||||
# 这个脚本以 root 运行，所以：只读取普通文件（不跟符号链接）、读取之后先复制到自己的临时目录再验证和使用（防止验证之后被换掉），
|
||||
# 并且绝不往 update/ 里写任何东西；状态写在 root 拥有的 update-status/ 里（业务进程只读）。
|
||||
UPDATE_DIR="$DATA_DIR/update"
|
||||
STATUS_DIR="$DATA_DIR/update-status"
|
||||
STATUS="$STATUS_DIR/status.json"
|
||||
INSTALLED="$STATE_DIR/$COMPONENT.installed" # 两行：seq、digest
|
||||
mkdir -p "$STATE_DIR" "$STATUS_DIR"
|
||||
chmod 755 "$STATUS_DIR"
|
||||
WORK="$(mktemp -d)"
|
||||
trap 'rm -rf "$WORK"' EXIT
|
||||
OFFER_MANIFEST="$WORK/offer.manifest"
|
||||
OFFER_SIG="$WORK/offer.sig"
|
||||
|
||||
# 把业务进程放的清单和签名复制到临时目录；不是普通文件（缺失、符号链接）就当作没有
|
||||
fetch_offer() {
|
||||
rm -f "$OFFER_MANIFEST" "$OFFER_SIG"
|
||||
for name in offer.manifest offer.sig; do
|
||||
f="$UPDATE_DIR/$name"
|
||||
if [ -f "$f" ] && [ ! -L "$f" ]; then head -c 8192 "$f" > "$WORK/$name"; fi
|
||||
done
|
||||
}
|
||||
|
||||
now() { date +%s; }
|
||||
|
||||
# 状态文件：Agent / Probe 读它并随心跳报给面板。root 写，业务进程只读。
|
||||
write_status() { # state available_json error
|
||||
tmp="$(mktemp "$STATUS_DIR/.status.XXXXXX")"
|
||||
printf '{"state":"%s","current":"%s","available":%s,"error":"%s","at":%s}\n' \
|
||||
"$1" "$(current_digest)" "${2:-null}" "$(printf '%s' "${3:-}" | tr -d '"\\\n' | cut -c1-200)" "$(now)" > "$tmp"
|
||||
chmod 644 "$tmp"
|
||||
mv -f "$tmp" "$STATUS"
|
||||
}
|
||||
|
||||
current_digest() { [ -r "$INSTALLED" ] && sed -n 2p "$INSTALLED" || echo ""; }
|
||||
installed_seq() { [ -r "$INSTALLED" ] && sed -n 1p "$INSTALLED" || echo 0; }
|
||||
|
||||
# 从扁平的清单里取字段（清单由 CI 生成，只有字符串和整数，没有嵌套）
|
||||
field() { sed -n 's/.*"'"$1"'":"\([^"]*\)".*/\1/p' "$OFFER_MANIFEST" | head -n 1; }
|
||||
num_field() { sed -n 's/.*"'"$1"'":\([0-9][0-9]*\).*/\1/p' "$OFFER_MANIFEST" | head -n 1; }
|
||||
|
||||
# 验签 + 字段校验。成功时设置 M_DIGEST、M_TAG、M_VERSION、M_SEQ；失败返回非 0，原因在 ERR。
|
||||
verify_offer() {
|
||||
ERR=""
|
||||
[ -s "$OFFER_MANIFEST" ] && [ -s "$OFFER_SIG" ] || { ERR="no offer"; return 1; }
|
||||
[ "$(wc -c < "$OFFER_MANIFEST")" -le 4096 ] || { ERR="manifest too large"; return 1; }
|
||||
sigbin="$WORK/sig.bin"
|
||||
base64 -d "$OFFER_SIG" > "$sigbin" 2>/dev/null || { ERR="bad signature encoding"; return 1; }
|
||||
openssl dgst -sha256 -verify "$PUBKEY" -signature "$sigbin" "$OFFER_MANIFEST" >/dev/null 2>&1 || { ERR="signature check failed"; return 1; }
|
||||
[ "$(field component)" = "$COMPONENT" ] || { ERR="manifest is for another component"; return 1; }
|
||||
[ "$(field image)" = "$IMAGE_REPO" ] || { ERR="manifest names another repository"; return 1; }
|
||||
M_DIGEST="$(field digest)"
|
||||
case "$M_DIGEST" in sha256:*) ;; *) ERR="bad digest"; return 1 ;; esac
|
||||
[ "${#M_DIGEST}" -eq 71 ] && [ -z "$(printf '%s' "${M_DIGEST#sha256:}" | tr -d '0-9a-f')" ] || { ERR="bad digest"; return 1; }
|
||||
M_TAG="$(field tag)"; M_VERSION="$(field version)"; M_SEQ="$(num_field seq)"
|
||||
[ -n "$M_SEQ" ] || { ERR="no seq"; return 1; }
|
||||
[ "$M_SEQ" -gt "$(installed_seq)" ] || { ERR="stale manifest (seq $M_SEQ <= $(installed_seq))"; return 1; }
|
||||
}
|
||||
|
||||
available_json() { printf '{"version":"%s","tag":"%s","digest":"%s","seq":%s}' "$(printf '%s' "$M_VERSION" | tr -d '"\\')" "$(printf '%s' "$M_TAG" | tr -d '"\\')" "$M_DIGEST" "$M_SEQ"; }
|
||||
|
||||
do_check() {
|
||||
fetch_offer
|
||||
if ! verify_offer; then
|
||||
# 没有新清单，或者清单已经安装过：不算错误，只是没有更新
|
||||
case "$ERR" in
|
||||
"no offer"|"stale manifest"*) write_status up_to_date null "" ;;
|
||||
*) write_status invalid null "$ERR"; echo "offer rejected: $ERR" >&2 ;;
|
||||
esac
|
||||
return 0
|
||||
fi
|
||||
if [ "$M_DIGEST" = "$(current_digest)" ]; then
|
||||
write_status up_to_date null ""
|
||||
return 0
|
||||
fi
|
||||
write_status available "$(available_json)" ""
|
||||
echo "update available: $M_TAG ($M_DIGEST)"
|
||||
if [ "$POLICY" = auto ]; then do_apply; fi
|
||||
return 0
|
||||
}
|
||||
|
||||
do_apply() {
|
||||
rm -f "$UPDATE_DIR/apply.request"
|
||||
fetch_offer
|
||||
verify_offer || { write_status invalid null "$ERR"; echo "refusing to apply: $ERR" >&2; return 1; }
|
||||
avail="$(available_json)"
|
||||
write_status applying "$avail" ""
|
||||
ref="$IMAGE_REPO@$M_DIGEST"
|
||||
if [ -n "${AUTHFILE:-}" ]; then export REGISTRY_AUTH_FILE="$AUTHFILE"; fi
|
||||
if ! podman pull --quiet "$ref" >/dev/null 2>&1; then
|
||||
write_status failed "$avail" "pull failed"; echo "pull failed: $ref" >&2; return 1
|
||||
fi
|
||||
prev="$(cat "$ENV_FILE" 2>/dev/null || true)"
|
||||
printf 'IMAGE=%s\n' "$ref" > "$ENV_FILE.new" && mv -f "$ENV_FILE.new" "$ENV_FILE"
|
||||
systemctl restart "$UNIT" || true
|
||||
# 健康确认：服务在跑，并且 20 秒内没有再被重启（崩溃循环算失败）
|
||||
sleep 5
|
||||
before="$(systemctl show -p NRestarts --value "$UNIT" 2>/dev/null || echo 0)"
|
||||
sleep 15
|
||||
after="$(systemctl show -p NRestarts --value "$UNIT" 2>/dev/null || echo 0)"
|
||||
if systemctl is-active --quiet "$UNIT" && [ "$before" = "$after" ]; then
|
||||
printf '%s\n%s\n' "$M_SEQ" "$M_DIGEST" > "$INSTALLED"
|
||||
write_status up_to_date null ""
|
||||
echo "updated to $M_TAG"
|
||||
return 0
|
||||
fi
|
||||
echo "new version did not become healthy, rolling back" >&2
|
||||
if [ -n "$prev" ]; then printf '%s\n' "$prev" > "$ENV_FILE"; fi
|
||||
systemctl restart "$UNIT" || true
|
||||
write_status rolled_back "$avail" "new version did not become healthy"
|
||||
return 1
|
||||
}
|
||||
|
||||
case "$CMD" in
|
||||
check) do_check ;;
|
||||
apply) do_apply ;;
|
||||
esac
|
||||
@@ -0,0 +1,4 @@
|
||||
-----BEGIN PUBLIC KEY-----
|
||||
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEfw7EkNcl0FZqOETK+Vt55RMZ9K0q
|
||||
YOrtO3Vso/QNdSMmepQlx1Q3v+KkN7ro3AY3I6DT2Q2txJu5pS7qzutSQA==
|
||||
-----END PUBLIC KEY-----
|
||||
Reference in new issue
Block a user