โปรโตคอลการสื่อสาร

เอกสารนี้ระบุรูปแบบการโยงที่สมบูรณ์ระหว่าง agent, exchange และ cli คำจำกัดความอยู่ใน crates/proto และทั้งสามใช้รหัสเดียวกัน: ฟิลด์ถูกกำหนดไว้ในที่เดียว ดังนั้นความไม่สอดคล้องกันจึงปรากฏขึ้นในเวลาคอมไพล์ แทนที่จะเป็นในระหว่างเซสชันการใช้งานจริง

ให้บริการแก่ผู้ให้บริการตรวจสอบการรับส่งข้อมูลเครือข่ายเพื่อวินิจฉัยปัญหา และนักพัฒนาเปลี่ยนโปรโตคอลหรือเขียนไคลเอนต์บุคคลที่สาม

สารบัญ

• ภาพรวม
• การขนส่งและจุดสิ้นสุด
• เวอร์ชันโปรโตคอล
• ข้อความควบคุม
  • DeviceUp (agent → exchange)
  • อุปกรณ์ลง (exchange → agent)
  • OperatorUp (cli → exchange)
  • ตัวดำเนินการลง (exchange → cli)
  • โครงสร้างข้อมูลที่ใช้ร่วมกัน
• เฟรมข้อมูลไบนารี
• Session ID การแปลระหว่างสองเนมสเปซ
• ลำดับการจับมือ
• Eการจัดการข้อผิดพลาดและความล้มเหลวหมวดหมู่
• Keepalive และหมดเวลา
• แรงดันย้อนกลับ
• Android การควบคุมหน้าจอ
• Eเซสชันที่ปิดผนึกตั้งแต่ต้นทางถึงปลายทาง

ภาพรวม

โปรโตคอลมีสองชั้นที่ใช้การเชื่อมต่อ WebSocket ร่วมกัน:

การฝังข้อมูลสตรีมมิ่งใน JSON เป็น base64 จะเพิ่มขนาดขึ้นประมาณ 33% การรับส่งข้อมูล PTY ประกอบด้วยแพ็กเก็ตขนาดเล็กบ่อยครั้งซึ่งสะท้อนการกดแป้นพิมพ์แต่ละครั้ง ดังนั้นโอเวอร์เฮดนี้จึงส่งผลโดยตรงต่อเวลาแฝงของการโต้ตอบ ข้อความควบคุมไม่บ่อยนัก ทำให้การอ่าน JSON มีคุณค่ามากขึ้น: การจับแพ็กเก็ตสามารถเข้าใจได้ทันที

ตามแบบแผน แต่ละเฟรมไบนารี WebSocket ** จะมีหนึ่งเฟรมข้อมูล** เท่านั้น ไบต์ที่เกินหรือหายไปถือเป็นข้อผิดพลาด

การขนส่งและจุดสิ้นสุด

ทั้งสองเส้นทางใช้ประเภทข้อมูลรับรองแยกกัน โทเค็นอุปกรณ์ไม่สามารถเข้าถึงจุดสิ้นสุดของผู้ให้บริการ และในทางกลับกัน

ข้อมูลประจำตัวของผู้ให้บริการใช้ส่วนหัวของคำขอแทนที่จะเป็นสตริงการสืบค้น URL เนื่องจาก URL ปรากฏในบันทึกพร็อกซีย้อนกลับ ประวัติเบราว์เซอร์ และส่วนหัวของผู้อ้างอิง โทเค็นอุปกรณ์ใช้เฟรมแรกแทนที่จะเป็นส่วนหัวคำขอ เนื่องจากไคลเอ็นต์แบบฝังบางตัวไม่สามารถปรับแต่งส่วนหัว handshake ของ WebSocket ได้อย่างง่ายดาย วิธีเฟรมแรกยังอนุญาตให้รุ่นโปรโตคอลไม่ตรงกันและโทเค็นที่ไม่ถูกต้องเพื่อใช้ข้อความตอบกลับเดียวกัน

การใช้งานจริงต้องใช้ wss://: ข้อมูลประจำตัวทั้งสองประเภทจะปรากฏเป็นข้อความธรรมดาระหว่างการจับมือกัน

เวอร์ชันโปรโตคอล

pub const PROTOCOL_VERSION: u16 = 1;

มีการเปรียบเทียบเวอร์ชันทั้งสองทิศทางระหว่างการจับมือกัน ความไม่ตรงกันทำให้เกิดการปฏิเสธทันทีพร้อมคำอธิบายที่ชัดเจน วิธีนี้จะป้องกันไม่ให้เวอร์ชันที่ไม่ตรงกันปรากฏเป็นความล้มเหลวในการแยกวิเคราะห์ที่อธิบายไม่ได้ในข้อความในภายหลัง ซึ่งอาจเป็นเรื่องยากที่จะวินิจฉัย

• ฝั่งอุปกรณ์: agent มีเวอร์ชันอยู่ใน register ในกรณีที่ไม่ตรงกัน เซิร์ฟเวอร์ส่งคืน register_ack ด้วย ok: false อธิบายทั้งสองเวอร์ชันใน error และปิดการเชื่อมต่อ
• ฝั่งผู้ดำเนินการ: เซิร์ฟเวอร์จะส่ง welcome ในเชิงรุกหลังจากสร้างการเชื่อมต่อ หาก CLI ตรวจพบความไม่ตรงกัน ระบบจะรายงานข้อผิดพลาดและแนะนำให้ผู้ใช้อัปเกรดเป็นเวอร์ชันที่ตรงกับ server_version

ข้อความที่ไม่รู้จัก ค่า type จะถูกปฏิเสธเสมอ ไม่เคยตีความว่าเป็นประเภทที่รู้จักโดยไม่โต้ตอบ

ควบคุมข้อความ

ข้อความควบคุมทั้งหมดเป็นอ็อบเจ็กต์ JSON ที่แท็กโดยฟิลด์ type (serde enum ที่แท็กภายใน) ค่าแท็กและชื่อฟิลด์ใช้ snake_case session_id ได้รับการซีเรียลไลซ์อย่างโปร่งใสเป็นตัวเลขธรรมดา

อุปกรณ์ขึ้น (agent → exchange)

register ตัวที่สองบนการเชื่อมต่อที่ลงทะเบียนไว้แล้วจะถือเป็นการใช้โปรโตคอลในทางที่ผิดและบันทึกเป็นคำเตือน

ตัวอย่าง:

{"type":"register","protocol_version":1,"device_id":"lab-router","token":"a1b2….c2Vj…","info":{"hostname":"OpenWrt","model":"ath79/generic","openwrt_version":"OpenWrt 23.05.5","kernel":"5.15.137","arch":"mips","agent_version":"0.1.0"}}
{"type":"exec_exit","session_id":31,"code":0,"timed_out":false}

อุปกรณ์ลง (exchange → agent)

OperatorUp (cli → exchange)

การตรวจสอบความถูกต้องเกิดขึ้นระหว่างการจับมือ WebSocket ดังนั้นจึงไม่มีข้อความเข้าสู่ระบบ

session_id ในข้อความ open_* ทั้งสี่ข้อความคือ ** จัดสรรโดย CLI เอง** (ดู Session ID Translation ระหว่างสอง Namespaces) อนุญาตให้ใช้เฟรมที่ตามมาทันทีหลังจากการร้องขอโดยไม่ต้องรอการตอบรับ ID

ตัวดำเนินการลง (exchange → cli)

โครงสร้างข้อมูลที่ใช้ร่วมกัน

ExecHoldInfo: job_id, kind (exec / download / upload / file), age_secs, session_id?, command_preview, status, timeout_secs, started_at_unix_ms, exit_code?, timed_out. เพื่อความเข้ากันได้ kind ที่หายไปจะมีค่าเริ่มต้นเป็น exec และไม่มี age_secs ที่มีค่าเริ่มต้นเป็น 0 รายการคำตอบจะคำนวณอายุจากนาฬิกาปัจจุบัน สรุปพาธคำสั่ง/ไฟล์จำกัดอยู่ที่ประมาณ 120 อักขระ งานที่ไม่ใช่ exec รองรับการ kill เท่านั้น ไม่ใช่ tail/cat/attach

DeviceSessionInfo: session_id: u32 (ID ฝั่งอุปกรณ์), operator_session_id: u32, kind: string, hold: bool, age_secs: u64, deadline_unix_ms: u64 Exchange ตอบกลับรายการเซสชันและคำขอการยกเลิกที่บังคับโดยตรงโดยไม่ต้องเปิดเซสชันอุปกรณ์อื่น บัญชีแบบอ่านอย่างเดียวจะได้รับ forbidden

DeviceInfo

ข้อมูลอุปกรณ์แบบคงที่ รายงานหนึ่งครั้งใน register และจัดเก็บไว้ใน devices.info ทุกอย่างยกเว้น agent_version เป็นทางเลือก: แหล่งที่มาส่วนใหญ่จะไม่พร้อมใช้งานเมื่อ agent ทำงานภายนอก OpenWrt เช่น บนเครื่องพัฒนาหรือในคอนเทนเนอร์ การลงทะเบียนควรจะสำเร็จมากกว่าการเริ่มต้นล้มเหลว ช่องที่ขาดหายไปจะถูกละเว้นระหว่างการทำให้เป็นอนุกรม

Metrics

รวบรวมอีกครั้งสำหรับแต่ละฮาร์ตบีต โดยใช้เฉพาะค่าที่มีอยู่โดยตรงจาก /proc โดยไม่ต้องฟอร์กกระบวนการย่อย ความล้มเหลวในการอ่านรายการเดียวไม่ได้ทำให้คอลเลกชันทั้งหมดล้มเหลว: การสูญเสียการวัดหนึ่งรายการจะดีกว่าความล้มเหลวของฮาร์ทบีททั้งหมด และการรายงานอุปกรณ์ออฟไลน์อย่างไม่ถูกต้อง

InterfaceStats: { name: string, rx_bytes: u64, tx_bytes: u64 }

เฟรมข้อมูลไบนารี

 0        1                    5                    9
 +--------+--------------------+--------------------+
 |  kind  |     session_id     |    payload_len     |  payload (payload_len 字节)
 |   u8   |    u32 (大端)      |    u32 (大端)      |
 +--------+--------------------+--------------------+
 └──────────── 9 字节定长头 ────────────┘

ประเภทสตรีม

หาก agent ได้รับ ExecStdout / ExecStderr ดาวน์สตรีม ระบบจะบันทึกคำเตือนและละทิ้งเฟรม ซึ่งบ่งชี้ถึงข้อผิดพลาดในการใช้งานที่เพียร์

หมายเหตุการออกแบบ

**payload_len นั้นซ้ำซ้อนกับฟิลด์ความยาว WebSocket ** มันยังคงอยู่ด้วยเหตุผลสองประการ: การถอดรหัสสามารถตรวจจับการตัดทอน (การประกาศ 11 ไบต์โดยมีเพียง 5 ที่ให้มาจะต้องถูกปฏิเสธ แทนที่จะยอมรับโดยไม่แจ้งให้ทราบว่าเป็นแพ็กเก็ตที่สั้นกว่า) และรูปแบบเฟรมจะยังคงไม่เปลี่ยนแปลงหากจำเป็นต้องใช้ TCP แบบดิบในภายหลัง

ขีดจำกัดเพย์โหลด 1 MiB ไม่ได้มีไว้สำหรับการรับส่งข้อมูลปกติ: PTY และเอาต์พุตคำสั่งเป็นสตรีมส่วนเพิ่มที่เล็กกว่านั้นมาก ป้องกันไม่ให้เพียร์ใช้หน่วยความจำเซิร์ฟเวอร์จนหมดด้วยส่วนหัวที่อ้างว่ามีเพย์โหลด 2 GiB

เพย์โหลด Empty ถูกต้อง: การอ่านแบบศูนย์ไบต์บางครั้งเกิดขึ้นในเซสชัน PTY เฟรมดังกล่าวประกอบด้วยส่วนหัวขนาด 9 ไบต์เพียงอย่างเดียว

เพย์โหลดมีไบต์ที่กำหนดเอง รวมถึงลำดับที่ไม่ใช่ UTF-8 และต้องได้รับการเก็บรักษาไว้อย่างถูกต้อง

ข้อผิดพลาดในการถอดรหัส

ความล้มเหลวในการถอดรหัส data-frame ส่งผลต่อเฟรมนั้นเท่านั้น: exchange บันทึกคำเตือนและละทิ้งโดยไม่ยกเลิกการเชื่อมต่อ

การแปลรหัสเซสชันระหว่างสองเนมสเปซ

นี่คือส่วนหนึ่งของโปรโตคอลที่เข้าใจผิดได้ง่ายที่สุด

ในประโยคเดียว

initiator จัดสรร session_id ซึ่งเป็น unique ภายในการเชื่อมต่อของตัวเองเท่านั้น การเชื่อมต่อระหว่างโอเปอเรเตอร์และอุปกรณ์จะรักษาเนมสเปซ ID อิสระ และ exchange จะแปลระหว่างทั้งสอง เซสชันโลจิคัลหนึ่งเซสชันมี ID ที่แตกต่างกันสองรหัส

  remote-cli                    exchange                      remote-agent
                                                        （设备 lab-router）

  ┌────────────┐        ┌────────────────────┐            ┌────────────┐
  │ 运维编号   │        │      路由表        │            │ 设备编号   │
  │  空间      │        │                    │            │  空间      │
  │            │        │  lab-router:       │            │            │
  │  session 7 │───────▶│    31 → (op-A, 7)  │───────────▶│ session 31 │
  │            │◀───────│                    │◀───────────│            │
  └────────────┘        │  op-A:             │            └────────────┘
                        │    7 → (lab-router,│
   由 CLI 自己的        │         31)        │             由 exchange
   SessionIdGenerator   └────────────────────┘             的 DeviceHandle
   分配（1,2,3…）                                          分配（1,2,3…）

ทำไมต้องออกแบบนี้

**Aหลีกเลี่ยงการเดินทางไปกลับ ** หากเซิร์ฟเวอร์จัดสรร ID ทั้งหมด CLI จะต้องรอการตอบรับโดยแจ้งว่า ID เซสชันคือ 31 ก่อนที่จะส่งอินพุตคีย์บอร์ดหลังจากเปิด PTY การจัดสรร CLI อนุญาตเฟรมข้อมูลทันทีหลังจาก open_pty

**Aหลีกเลี่ยงการชนกันของ ID ระหว่างตัวดำเนินการ ** ตัวดำเนินการสองคนอาจใช้ ID ท้องถิ่น 1 บนอุปกรณ์เดียวกันพร้อมกัน อุปกรณ์จะต้องแยกแยะความแตกต่างเหล่านี้เพื่อหลีกเลี่ยงการส่งเอาต์พุตของบุคคลหนึ่งไปยังอีกบุคคลหนึ่ง exchange จัดสรร ID ฝั่งอุปกรณ์แยกกันสำหรับการเชื่อมต่ออุปกรณ์แต่ละรายการ โดยจับคู่อินสแตนซ์ session 1 สองตัวกับ 31 ฝั่งอุปกรณ์และ 32

**ป้องกันพฤติกรรมของผู้ปฏิบัติงานไม่ให้ส่งผลต่อ ID ฝั่งอุปกรณ์ ** exchange ควบคุม ID ฝั่งอุปกรณ์ทั้งหมด ไม่มีผู้ปฏิบัติงานสามารถระบุหรือคาดเดาได้

สองโต๊ะ

exchange รักษาหนึ่งตารางต่อการเชื่อมต่อ โดยทั้งสองตารางจะอัปเดตร่วมกันเสมอ:

ดัชนีย้อนกลับช่วยให้สามารถล้างข้อมูลได้: เมื่อผู้ปฏิบัติงานตัดการเชื่อมต่อ เซิร์ฟเวอร์จะต้องค้นหาและยุติเซสชันบนอุปกรณ์ e ทุกเครื่อง ไม่เช่นนั้น กระบวนการและ PTY ที่ไม่มีผู้รับเอาต์พุตจะยังคงอยู่

การแปลเกิดขึ้นที่ไหน

การแปลเฟรมข้อมูลคือการเขียนใหม่ only: exchange จะไม่แยกวิเคราะห์ บัฟเฟอร์ หรือเปลี่ยนเพย์โหลดไบต์ใดๆ DataFrame::with_session_id แทนที่ ID ที่มีอยู่โดยไม่ต้องจัดสรรเพย์โหลดใหม่

กฎการจัดสรร

ตัวจัดสรรทั้งสองเพิ่มขึ้นจาก 1 และ skip 0 ซึ่งเป็น no-session sentinel ที่ใช้ใน ตัวอย่างเช่น ในข้อความแสดงข้อผิดพลาดระดับการเชื่อมต่อ

• CLI (SessionIdGenerator): wraps บนโอเวอร์โฟลว์และข้าม 0 การใช้สี่พันล้านเซสชันในการเชื่อมต่อเดียวนั้นไม่สมจริง แต่การ wraps เหมาะกับกระบวนการที่ใช้เวลานานมากกว่าการตื่นตระหนก
• อุปกรณ์ (DeviceHandle::open_session): หลังจากสรุปแล้ว หาก ID อยู่ในเซสชันสด ให้ดำเนินการต่อไปยังช่องว่างถัดไป

exchange ปฏิเสธ ID ตัวดำเนินการ 0 และการนำ ID เซสชันที่ใช้งานอยู่กลับมาใช้ใหม่ ความถูกต้องของการเชื่อมต่ออุปกรณ์ ขีดจำกัดการทำงานพร้อมกัน และการลงทะเบียนในดัชนีทั้งสองจะได้รับการตรวจสอบภายในส่วนสำคัญเดียวกัน ป้องกันไม่ให้เซสชันที่เปิดพร้อมกันจากผู้ให้บริการหลายรายเกินขีดจำกัด

เมื่อไม่มีเส้นทาง

** ทิ้งอย่างเงียบๆ โดยไม่มีข้อผิดพลาด ** เพียร์ที่ยังคงส่งข้อมูลต่อท้ายหลังจากปิดเซสชันถือเป็นการแข่งขันปกติ สิ่งนี้ใช้ได้กับทั้งสองทิศทาง:

• อุปกรณ์ตอบกลับสำหรับเซสชันที่ไม่มีอยู่อีกต่อไป → บันทึกการแก้ไขข้อบกพร่อง ผู้ดำเนินการอาจตัดการเชื่อมต่อไปแล้ว
• ผู้ดำเนินการส่งข้อมูลสำหรับเซสชันที่ไม่ได้รับอนุญาต → ติดตามบันทึกและละทิ้ง

เส้นทางการล้างข้อมูลเซสชัน

ดัชนีย้อนกลับเชื่อมโยงกับการเชื่อมต่ออุปกรณ์เฉพาะ จะไม่เปลี่ยนเส้นทางตามรหัสอุปกรณ์ไปยังการเชื่อมต่อใหม่หลังจากการเชื่อมต่อใหม่ การเชื่อมต่อของผู้ให้บริการหลายรายสำหรับบัญชีหนึ่งแต่ละบัญชีเป็นเจ้าของดัชนี ดังนั้นการยกเลิกการเชื่อมต่อจะไม่ยกเลิกเซสชันของการเชื่อมต่ออื่น

การรับทราบสำหรับการยกเลิกอย่างชัดเจน: exec ส่งคืน exec_exit (code: null, timed_out: false), PTY ส่งคืน pty_closed (code: null) และ ubus ส่งคืน session_failed (reason: device_error) นี่เป็นการยืนยันว่า exchange ได้ปิดเซสชันแล้ว ไม่ใช่ว่ากระบวนการระยะไกลได้ออกจากไปแล้ว ข้อมูลต่อท้ายและข้อความออกที่ตามมาจากอุปกรณ์จะถูกละทิ้ง

ที่ขีดจำกัดการทำงานพร้อมกัน Exchange จะเรียกคืนเส้นทางที่ตัวดำเนินการหายไปหรือเกินกำหนดเวลาภายใต้การล็อกเซสชันเดียวกันก่อน จากนั้นจึงตรวจสอบขีดจำกัดอีกครั้ง กำหนดเวลาของผู้บริหารคือขีดจำกัดเวลาจัดส่งจริงบวกกับระยะเวลาผ่อนผัน 15 วินาที ไฟล์ใช้เวลา 3600 วินาทีบวก 15 วินาที ประเภทอื่นใช้งานได้ 24 ชม. Hold exec ภายในกำหนดเวลาจะไม่ถูกฆ่าเมื่อผู้ปฏิบัติงานออกไป การเรียกคืน/อย่างชัดเจน kill_device_session จะส่งการยกเลิกที่เกี่ยวข้องไปยังอุปกรณ์และลบดัชนีทั้งสองออกทันทีโดยไม่ต้องรอการตอบสนองของอุปกรณ์ ตัวดำเนินการที่พร้อมใช้งานจะได้รับ exec_exit (timed_out:true) สำหรับ exec หรือ session_failed (device_error, session reclaimed) สำหรับประเภทอื่น การอัปเดตการตรวจสอบเป็นแบบอะซิงโครนัสและพยายามอย่างเต็มที่

การเชื่อมต่ออุปกรณ์ใหม่และยุค

การเชื่อมต่ออุปกรณ์แต่ละรายการจะได้รับ epoch (UUID) แบบสุ่มระหว่างการลงทะเบียน เมื่ออุปกรณ์เดียวกันเชื่อมต่อใหม่ ** การเชื่อมต่อใหม่จะแทนที่อันเก่า** แทนที่จะถูกปฏิเสธ เป็นไปไม่ได้ที่จะแยกแยะการเชื่อมต่อที่ซ้ำกันจากการเชื่อมต่อที่ไม่ทำงานซึ่งเซิร์ฟเวอร์ตรวจไม่พบ (การเชื่อมต่อแบบเปิดครึ่งหนึ่ง) ได้อย่างน่าเชื่อถือ การปฏิเสธอันใหม่จะป้องกันการเชื่อมต่อใหม่จนกว่าอันเก่าจะหมดเวลา

การล้างข้อมูลสำหรับการเชื่อมต่อเก่าอาจดำเนินการลงทะเบียน after ของการเชื่อมต่อใหม่ การยกเลิกการลงทะเบียนจึงต้องตรวจสอบยุค: ลบรายการตารางการเชื่อมต่อเฉพาะเมื่อยุคปัจจุบันตรงกับการเชื่อมต่อที่กำลังล้างข้อมูล หากไม่มีการตรวจสอบนี้ การล้างข้อมูลการเชื่อมต่อเก่าจะทำเครื่องหมายอุปกรณ์ที่เชื่อมต่อใหม่เป็นออฟไลน์ทันที

ลำดับการจับมือ

ด้านอุปกรณ์

  remote-agent                                        exchange
      │                                                 │
      │  ①  WebSocket 握手（wss://host/ws/device）      │
      │────────────────────────────────────────────────▶│
      │◀────────────────────────────────────────────────│
      │            101 Switching Protocols              │
      │                                                 │
      │                                          ┌──────┴──────┐
      │                                          │ 启动 15 秒  │
      │                                          │ 注册计时器  │
      │                                          └──────┬──────┘
      │  ②  {"type":"register","protocol_version":1,    │
      │      "device_id":"…","token":"…","info":{…}}    │
      │────────────────────────────────────────────────▶│
      │                                                 │
      │                              ┌──────────────────┴──────────────────┐
      │                              │ a. 比对 protocol_version            │
      │                              │ b. split_token → 前缀查 devices 表  │
      │                              │ c. 校验 enabled                     │
      │                              │ d. argon2 verify（前缀不符也照做，  │
      │                              │    避免用耗时区分前缀是否存在）     │
      │                              └──────────────────┬──────────────────┘
      │                                                 │
      │  ③  {"type":"register_ack","ok":true,           │
      │      "error":null,"heartbeat_interval_secs":30} │
      │◀────────────────────────────────────────────────│
      │                                                 │
      │                                          ┌──────┴──────┐
      │                                          │ 登记连接表  │
      │                                          │ 顶替旧连接  │
      │                                          │ 回写 info 与│
      │                                          │ last_seen_at│
      │                                          └──────┬──────┘
      │                                                 │
      │  ④  退避曲线复位，写状态文件 state=connected     │
      │                                                 │
      │══════════════ 转发循环 ═══════════════════════════│
      │                                                 │
      │  heartbeat（每 30 秒，携带 Metrics）             │
      │────────────────────────────────────────────────▶│
      │  WebSocket Ping（随每次 heartbeat 发出）         │
      │────────────────────────────────────────────────▶│
      │                                     WebSocket Pong
      │◀────────────────────────────────────────────────│
      │                                     WebSocket Ping（每 30 秒）
      │◀────────────────────────────────────────────────│
      │  Pong（tungstenite 排队，agent 显式 flush）       │
      │────────────────────────────────────────────────▶│

เส้นทางความล้มเหลว:

• เฟรมแรกไม่ใช่ข้อความ เป็น JSON ไม่ถูกต้อง หรือไม่ใช่ register → บันทึกคำเตือนและปิดทันทีโดยไม่มีแอก
• ไม่มี register ภายใน 15 วินาที → ปิด
• เวอร์ชันไม่ตรงกัน → ส่งคืน register_ack{ok:false, error:"协议版本不匹配：设备为 X，服务端为 Y"} และปิด
• โทเค็นไม่ถูกต้อง / อุปกรณ์ไม่มีอยู่ / อุปกรณ์ที่ปิดใช้งาน → ส่งคืน "设备 ID 或令牌无效" เดิมเสมอและปิด อย่าแยกแยะสาเหตุ: การทำเช่นนั้นจะทำให้สามารถนับรายการอุปกรณ์ได้

agent จัดการหมวดหมู่ความล้มเหลวทั้งสองนี้แยกกัน:

**Backoff จะรีเซ็ตหลังจากการลงทะเบียนสำเร็จแล้วเท่านั้น ** ไม่ใช่เฉพาะการสร้าง TCP เท่านั้น มิฉะนั้น การปฏิเสธทันทีหลังจากการเชื่อมต่อจะลดลงเป็นการลองใหม่อย่างหนาแน่นในช่วงเวลามิลลิวินาที

**Jitter เป็นสิ่งจำเป็น ** เมื่อเซิร์ฟเวอร์รีสตาร์ท อุปกรณ์หลายร้อยหรือหลายพันเครื่องจะตรวจพบการตัดการเชื่อมต่อพร้อมกัน ด้วยกราฟการลองซ้ำตามที่กำหนดที่เหมือนกัน พวกมันยังคงซิงโครไนซ์และโจมตีเซิร์ฟเวอร์ที่เพิ่งเริ่มต้นใหม่เป็นระลอก เปลี่ยนการรีสตาร์ทเป็นความล้มเหลวแบบเรียงซ้อนอย่างต่อเนื่อง

ฝั่งโอเปอเรเตอร์

  remote-cli                                          exchange
      │                                                 │
      │  ①  WebSocket 握手（wss://host/ws/operator）    │
      │      Authorization: Bearer <prefix>.<secret>    │
      │────────────────────────────────────────────────▶│
      │                                                 │
      │                              ┌──────────────────┴──────────────────┐
      │                              │ 在 upgrade 之前完成鉴权：           │
      │                              │ split_token → 前缀查 operators 表   │
      │                              │ → argon2 verify → 校验 enabled      │
      │                              └──────────────────┬──────────────────┘
      │                                                 │
      │      鉴权失败 → HTTP 401「凭证无效」（不升级）   │
      │◀────────────────────────────────────────────────│
      │                                                 │
      │◀────────────────────────────────────────────────│
      │            101 Switching Protocols              │
      │                                                 │
      │  ②  {"type":"welcome","protocol_version":1,     │
      │      "server_version":"0.1.0"}                  │
      │◀────────────────────────────────────────────────│
      │                                                 │
      │  ③  比对 protocol_version（15 秒超时）          │
      │      不一致 → 报错退出，提示升级 CLI            │
      │                                                 │
      │══════════════ 可以发起会话 ═══════════════════════│
      │                                                 │
      │  {"type":"open_pty","session_id":1,             │
      │   "device_id":"lab-router","rows":40,"cols":120}│
      │────────────────────────────────────────────────▶│
      │                                                 │──▶ 查设备在线
      │                                                 │──▶ 查并发上限
      │                                                 │──▶ 查 readonly 角色
      │                                                 │──▶ 写审计（先于下发）
      │                                                 │──▶ 分配设备侧编号
      │  二进制帧（PtyData, session 1, 键盘输入）        │
      │────────────────────────────────────────────────▶│──▶ 改写为设备侧编号
      │                                                 │
      │  二进制帧（PtyData, session 1, 屏幕输出）        │
      │◀────────────────────────────────────────────────│◀── 改写为运维侧编号

CLI สามารถส่งเฟรมข้อมูลถัดไป ** โดยไม่ต้องรอการตอบรับใดๆ** นี่เป็นสาเหตุที่แน่ชัดว่าเหตุใดผู้ริเริ่มจึงจัดสรร ID เซสชัน

หมวดหมู่การจัดการข้อผิดพลาดและความล้มเหลว

SessionFailure

ใช้ในฟิลด์ reason ของ session_failed; ค่า JSON ใช้ Snake_case

is_retryable() จงใจยกเว้น forbidden และ device_error: การลองปัญหาการอนุญาตอีกครั้งหรือข้อผิดพลาดของอุปกรณ์ภายในไม่มีจุดหมายและทำให้เกิดกิจกรรม CLI ที่ไม่จำเป็นเท่านั้น

CLI ผนวกคำใบ้ที่สามารถดำเนินการได้ต่อท้าย message ดั้งเดิม ตัวอย่างเช่น device_offline แนะนำให้ตรวจสอบสถานะอุปกรณ์ด้วย remote-cli device list device_error เป็นข้อยกเว้น: ข้อผิดพลาดของอุปกรณ์เองเป็นคำอธิบายที่ถูกต้องที่สุด และไม่ควรเจือจางด้วยแผ่นสำเร็จรูป

ความหมายความล้มเหลวตามเลเยอร์

หลักการ: รักษาความล้มเหลวในเครื่องทุกครั้งที่เป็นไปได้ เนื่องจากการเชื่อมต่ออุปกรณ์อาจมีเซสชันพร้อมกันสำหรับผู้ให้บริการหลายราย

Keepalive และหมดเวลา

ไคลเอ็นต์เชลล์ที่ไม่ได้ใช้งานยังคงตอบกลับด้วย Pong agent ล้างการตอบสนองโดยอัตโนมัติซึ่งจัดคิวโดยไลบรารีอย่างชัดเจน โดยไม่ต้องรอจังหวะการเต้นของหัวใจทางธุรกิจครั้งถัดไป ดังนั้น การไม่มีอินพุตคีย์บอร์ดจึงไม่ทำให้เกิดการตัดการเชื่อมต่อที่ผิดพลาด (#42) --heartbeat-secs ต้องมากกว่า 0; ค่าที่ไม่ถูกต้องจะถูกปฏิเสธในระหว่างการแยกวิเคราะห์อาร์กิวเมนต์เริ่มต้น

แรงดันย้อนกลับ

exchange รักษาคิวการส่งแบบมีขอบเขตของข้อความ 512 สำหรับการเชื่อมต่อแต่ละรายการ

คิวเต็มหมายความว่าเพียร์ไม่สามารถตามได้ โดยปกติแล้วเนื่องจากการเชื่อมต่อ PTY หยุดทำงานหรือไคลเอนต์ถูกระงับ การตอบสนองคือ ** ยกเลิกการเชื่อมต่อนั้นในเชิงรุก** แทนที่จะเก็บบัฟเฟอร์ไว้: การบัฟเฟอร์ที่ไม่จำกัดจะทำให้ไคลเอ็นต์ที่ค้างอยู่หนึ่งเครื่องกลายเป็นหน่วยความจำรั่วซึ่งส่งผลต่อบริการทั้งหมด ข้อความ 512 มีพื้นที่ว่างเพียงพอสำหรับการรับส่งข้อมูล PTY แบบโต้ตอบ (โดยปกติความยาวของคิวจะเป็นตัวเลขหลักเดียว) โดยทั่วไปการถึงขีดจำกัดหมายความว่าเพื่อนหยุดบริโภคแล้ว

การนำส่งใช้ try_send ที่ไม่ปิดกั้นเสมอ เส้นทางการเราต์มีการล็อคตารางการเชื่อมต่อ await ใดๆ จะผูกระยะเวลาการล็อกกับความเร็วในการใช้เพียร์ ซึ่งช่วยให้ไคลเอ็นต์ที่ช้าสามารถหยุดทั้งตารางได้

ความล้มเหลวในการจัดส่งทั้งสองรายการได้รับการจัดการที่แตกต่างกัน:

สัญญาณการปิดการเชื่อมต่อจะข้ามคิวการส่ง ช่วยให้สามารถล้างข้อมูลได้แม้ว่าคิวจะเต็มหรือการเขียนถูกบล็อกก็ตาม การเปลี่ยนอุปกรณ์หลังจากเชื่อมต่อใหม่และการหมุนโทเค็นจะใช้กลไกเดียวกัน

agent ยังมีคิวขาออกที่มีความจุ 256 คิวเต็มหมายความว่าเครือข่ายไม่สามารถส่งข้อมูลได้เลย ดังนั้นการสะสมเพิ่มเติมจึงไม่มีประโยชน์ ตัดการเชื่อมต่อและเชื่อมต่อใหม่ เมื่อคิวอินพุต PTY (64) เต็ม การกดแป้นพิมพ์จะถูกละทิ้งไป: การสะสมอินพุตโต้ตอบขนาดเล็กนั้นไม่ได้มีวัตถุประสงค์

การควบคุมหน้าจอ Android

กำหนดใน crates/proto/src/android.rs โดยใช้การกำหนดเส้นทางเซสชันสองเนมสเปซที่มีอยู่ การรับรองความถูกต้อง ขีดจำกัดการทำงานพร้อมกัน และการตรวจสอบ request ใน open_android / android_req เป็นอ็อบเจ็กต์ JSON ที่ถูกแยกโดย action:

AndroidResult ถูกเลือกปฏิบัติโดย kind; ต้องระบุข้อมูลทุกช่อง:

โหนดประกอบด้วยสตริง class_name, package, view_id, text, description, bounds: [left, top, right, bottom] (พิกัดพิกเซลของหน้าจอที่ลงนาม) และบูลีน clickable, editable, focused, password สูงสุด 200 โหนด โดยแต่ละสตริงจำกัดไว้ที่ 256 UTF-16 ยูนิต truncated ระบุเฉพาะขีดจำกัดของโหนด ค่ารหัสผ่านและคำอธิบายว่างเปล่า และละเว้นแผนผังย่อยการกำหนดค่าของ agent เอง

ขอบที่ยาวที่สุดของภาพหน้าจอจำกัดไว้ที่ 1600 พิกเซล width/height คือขนาดภาพ screen_width/screen_height คือขนาดก่อนการปรับขนาด พิกัดท่าทางใช้ขนาดดั้งเดิม JSON ที่ส่งคืนโดย Java Bridge ถูกจำกัดไว้ที่ 2 MiB โดยอนุญาตให้มีไบต์เพิ่มเติม 1024 ไบต์สำหรับซองจดหมาย WebSocket ไม่มีการเพิ่มประเภทเฟรมไบนารีใหม่

{"type":"open_android","session_id":1,"device_id":"phone","request":{"action":"input_text","text":"Hello\nWorld"}}
{"type":"android_req","session_id":31,"request":{"action":"input_text","text":"Hello\nWorld"}}
{"type":"android_resp","session_id":31,"result":{"kind":"ok"}}
{"type":"android_resp","session_id":1,"result":{"kind":"ok"}}

screen_capture_enabled บ่งชี้ถึงการอนุญาตภาพหน้าจอที่มีอยู่ในปัจจุบัน (MediaProjection หรือการเข้าถึง Android 11+) การใช้งานหน้าจอจริงทั้งหมดยังต้องใช้ controls_enabled สิทธิ์ไม่เพียงพอ หน้าต่างที่ไม่สามารถเข้าถึงได้ และการดำเนินการที่ล้มเหลวจะส่งคืน agent session_error ซึ่งแปลโดย Exchange เป็น session_failed เอเจนต์ที่ไม่ใช่ Android ส่งคืนข้อผิดพลาดที่ไม่สนับสนุนอย่างชัดเจน

Agent จัดการคำขอ Android ได้สูงสุด 4 รายการพร้อมกัน และเข้ารหัสภาพหน้าจอเพียงครั้งละหนึ่งรายการเท่านั้น การดำเนินการ Java รอสูงสุด 10 วินาที (สูงสุด 5 วินาทีสำหรับเฟรมหน้าจอ) การหมดเวลาคำขอ agent คือ 15 วินาที, การหมดเวลาของ CLI 20 วินาที ในการยกเลิกหรือยกเลิกการเชื่อมต่อของผู้ดำเนินการ Exchange จะส่ง android_cancel; agent ปิดซ็อกเก็ตในเครื่องและ APK จะยกเลิกงานที่อยู่ในคิวซึ่งยังไม่ได้ทำงาน ท่าทางหรือการเปลี่ยนแปลงข้อความที่เสร็จสมบูรณ์จะไม่ถูกย้อนกลับ

การดำเนินการตรวจสอบคือ android; รายละเอียดเก็บการกระทำและพิกัด input_text เก็บเฉพาะ characters (จำนวนอักขระ Unicode) และผลลัพธ์ที่สำเร็จจะบันทึกเฉพาะ outcome: "completed" เท่านั้น เนื้อหาข้อความ แผนผัง UI และรูปภาพไม่ได้ถูกเขียนลงในบันทึกการตรวจสอบ บัญชี readonly ไม่สามารถเริ่มต้นได้แม้แต่ status, tree หรือภาพหน้าจอ

ส่วนขยายเซสชันของไฟล์

เอเจนต์ที่สนับสนุนการดำเนินการกับไฟล์โฆษณาความสามารถ files Exchange แปล open_file {session_id, device_id, request} เป็น file_req {session_id, request} request.action คือ list, download หรือ upload; คำจำกัดความของฟิลด์อยู่ใน crates/proto/src/files.rs

ข้อความควบคุมแบบสองทิศทางใช้ JSON: ตัวควบคุมจะส่ง file_input {session_id, input} และอุปกรณ์ส่งคืน file_event {session_id, event} input.kind คือ chunk {offset, data}, ack {offset} หรือ finish; event.kind คือ ready {size}, chunk {offset, data}, progress {received}, complete {size} หรือ list {path, entries, truncated} เนื้อหาแบบก้อนใช้ Base64 มาตรฐาน แต่ละก้อนมีขนาดสูงสุด 64 KiB และผู้ส่งจะรอการตอบรับก่อนดำเนินการต่อ

ready เริ่มต้นของการดาวน์โหลดต้องใช้ ack {offset: 0}; ส่วนต่อมาจะรับทราบจำนวนไบต์สะสม การอัปโหลดเริ่มต้นด้วย ready และ progress แต่ละตัวจะขับเคลื่อนส่วนถัดไป หลังจากส่งทุกอย่างแล้ว finish จะคอมมิตมัน complete และ list เป็นข้อความเทอร์มินัล ข้อผิดพลาดใช้ session_error / session_failed ที่มีอยู่ close_session ส่ง file_cancel; การยกเลิกและการตัดการเชื่อมต่อทั้งลบเส้นทางเซสชัน ข้อความไฟล์จะถูกส่งต่อเฉพาะเซสชันไฟล์ โดยคงการแยกระหว่างรหัสโอเปอเรเตอร์และเซสชันอุปกรณ์

เวอร์ชันโปรโตคอลยังคงเป็น 1; ข้อความใหม่จำเป็นต้องมีการอัพเกรด Exchange และ Agent ที่ตรงกัน สำหรับขีดจำกัดการทำงานและอินเทอร์เฟซ LAN โปรดดูที่ การถ่ายโอนไฟล์และการเชื่อมต่อ LAN โดยตรง

ส่วนขยายหลายแพลตฟอร์ม

เวอร์ชันโปรโตคอลยังคงอยู่ 1. การลงทะเบียน info เพิ่มตัวเลือก platform (openwrt / linux / freebsd / netbsd / windows / android / macos) os_version และ capabilities (exec / pty / ubus / android_control / files / sensors / net) OpenWrt รายงาน openwrt_version

Heartbeat metrics.unavailable เป็นอาร์เรย์สตริงทางเลือกที่ระบุเมทริก uptime, load, memory, cpu และ interfaces ที่ไม่พร้อมใช้งานในปัจจุบัน หากไม่มี ให้แยกวิเคราะห์โดยใช้รูปแบบเก่า ค่าที่สอดคล้องกับเมตริกที่แสดงเป็นเพียงตัวยึดตำแหน่งที่เข้ากันได้เท่านั้น ลูกค้าควรแสดงว่าไม่พร้อมใช้งาน Windows ไม่ได้จัดเตรียมค่าเฉลี่ยโหลด Unix และ Android อาจจำกัดแหล่งที่มาของ /proc บางส่วนผ่านการอนุญาตของระบบ

คำสั่งถูกตีความโดยเชลล์ของอุปกรณ์เป้าหมาย: /bin/sh บน Linux/OpenWrt/macOS, PowerShell บน Windows และ /system/bin/sh บน Android รูปแบบเฟรม PTY และข้อความควบคุมเหมือนกันในทั้งสามระบบ Windows ใช้ ConPTY อุปกรณ์ที่ไม่ใช่ OpenWrt ส่งคืน session_error สำหรับคำขอ ubus

เซสชันที่ปิดผนึกตั้งแต่ต้นทางถึงปลายทาง

เวอร์ชันโปรโตคอลยังคงอยู่ 1. ข้อความใหม่: OperatorUp open_sealed {session_id, device_id, hello}, sealed_input {session_id, packet}; อุปกรณ์ลง sealed_open {session_id, hello}, sealed_input, sealed_close {session_id, detach}; อุปกรณ์ขึ้น / ตัวดำเนินการลง sealed_accept {session_id, accept}, sealed_event {session_id, packet, last} เฟรมไบนารีใหม่ประเภท 4 = Sealed (เพย์โหลด counter ‖ AEAD(inner_kind ‖ bytes)), DeviceInfo.seal_key และความสามารถ sealed

สำหรับเซสชันที่ปิดผนึก Exchange ดำเนินการเฉพาะการแปล ID การจำกัดการทำงานพร้อมกัน และการกำหนดเส้นทาง ไม่มีการแยกวิเคราะห์หรือตรวจสอบเพย์โหลด (บันทึกการตรวจสอบมีเพียงกุญแจสาธารณะ ระดับการอนุญาตและการหมดอายุ และผลลัพธ์สุดท้าย) และไม่ได้ตัดสินการอนุญาตนอกเหนือจากการตรวจสอบว่าบัญชีสามารถมองเห็นอุปกรณ์ได้หรือไม่ เส้นทางจะถูกเผยแพร่บน last:true เส้นทางที่ปิดผนึกยอมรับเฉพาะเฟรม Sealed เท่านั้น เส้นทางธรรมดาปฏิเสธเฟรม Sealed agent ละทิ้งข้อความธรรมดาใดๆ ที่ส่งไปยัง ID เซสชันที่ปิดผนึก สำหรับการอนุญาต การจับมือกัน การรับคีย์ โมเดลภัยคุกคาม โปรดดูที่ End-to-End Sealed Sessions