การพัฒนา

เอกสารนี้อธิบายวิธีสร้าง ทดสอบ และรัน exchange แบบโลคัลในที่เก็บนี้ ขั้นตอนการปรับใช้ ตารางฟิลด์โปรโตคอล และรายละเอียดการติดตั้งแพลตฟอร์มจะยังคงอยู่ในเอกสารเฉพาะที่ลิงก์ไว้ตอนท้าย

ทูลเชน

เวิร์กสเปซใช้ Rust 2021 และต้องการ Rust 1.88 หรือใหม่กว่า เวอร์ชันนี้ถูกบันทึกไว้ในฟิลด์ rust-version ของรูท Cargo.toml

พื้นที่ทำงานและไบนารี

เวิร์กสเปซ Rust มีสมาชิกเก้ารายการ ได้แก่ แปดรายการใน crates/ และ SDK สำหรับส่วนขยายใน sdk/extend/rust ชนิดข้อมูลของโปรโตคอลกำหนดไว้ที่ crates/proto เพียงแห่งเดียว โดย exchange, agent และ cli ใช้ crate นี้ร่วมกัน ห้ามกำหนดโครงสร้างข้อความซ้ำในแต่ละส่วนที่เรียกใช้

จุดเริ่มต้นสำหรับ exchange คือ crates/exchange/src/main.rs โดยไม่มีตาราง [[bin]] แยกต่างหาก ดังนั้น cargo build -p exchange จะสร้าง exchange รายการ agent และ cli (Cargo.toml) ตั้งชื่อไบนารีของตนอย่างชัดเจน remote-agent และ remote-cli

ตารางการเชื่อมต่อแบ่งตามความรับผิดชอบ:

• crates/exchange/src/hub.rs จัดการอุปกรณ์ออนไลน์ เชื่อมต่อการเปลี่ยนใหม่ และยุคสมัย
• crates/exchange/src/hub/session_table.rs แปล ID ฝั่งผู้ปฏิบัติงานและฝั่งอุปกรณ์
• crates/exchange/src/hub/outbound.rs จัดการคิวการส่งแบบมีขอบเขตสำหรับการเชื่อมต่อแต่ละรายการ

สร้าง

รันคำสั่งเหล่านี้จากรูทของที่เก็บ

โปรไฟล์รีลีส (opt-level = 2, Thin LTO, Unwind ยังคงอยู่) สร้างเซิร์ฟเวอร์, CLI และ Agent:

cargo build --release

ไบนารีตั้งอยู่ที่:

• target/release/exchange
• target/release/remote-cli
• target/release/remote-agent

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

อุปกรณ์ Agent ยังมีโปรไฟล์ที่ปรับขนาดให้เหมาะสม (opt-level = "z", LTO, panic = "abort", strip, codegen-units = 1):

cargo build -p agent --no-default-features --profile release-small

เอาต์พุตคือ target/release-small/remote-agent เนื่องจาก procd, systemd หรือ Task Scheduler รีสตาร์ท Agent หลังจากเกิดข้อขัดข้อง โปรไฟล์นี้สามารถแลกเปลี่ยน panic = "abort" สำหรับไบนารีที่เล็กกว่าได้

ฐานข้อมูลไม่จำเป็นสำหรับการคอมไพล์ crates/exchange/src/db.rs ใช้คำสั่งรันไทม์ sqlx แทนที่จะเป็นมาโคร query! ดังนั้น cargo build จึงทำงานโดยไม่มีฐานข้อมูล

การทดสอบ

cargo test --workspace

Windows ข้ามการทดสอบที่ต้องใช้ Unix /bin/sh (หรือ /bin/ash บน OpenWrt) และ PTY โมดูลทดสอบใน crates/agent/src/pty.rs ได้รับการปกป้องโดย #[cfg(all(test, unix))] และไม่ได้คอมไพล์บนแพลตฟอร์มที่ไม่ใช่ Unix การใช้งาน PTY จะพยายามใช้ /bin/ash จากนั้นจึงใช้ /bin/sh เส้นทางสัญญาณกลุ่มกระบวนการและ Unix ใน exec.rs ยังคอมไพล์บน Unix เท่านั้น การทดสอบคำสั่ง Windows ใช้ PowerShell โดยไม่ต้องเรียกใช้ /bin/sh หลังจากเปลี่ยนพาธ Unix ใน exec.rs หรือ pty.rs แล้ว ให้รัน cargo test --workspace บน Linux ด้วยเช่นกัน ผลลัพธ์ Windows เพียงอย่างเดียวไม่เพียงพอ

จำกัดขอบเขตให้เหลือเพียงลังเดียวเมื่อมีประโยชน์ เช่น cargo test -p proto หรือ cargo test -p exchange -- hub::

รัน exchange ภายในเครื่อง

เตรียม PostgreSQL และใส่สตริงการเชื่อมต่อใน DATABASE_URL ตัวแปรนี้แม็พกับอ็อพชัน exchange --database-url (ดู crates/exchange/src/config.rs) เมื่อเริ่มต้น db::connect จะรันการย้ายข้อมูลแบบฝัง ณ เวลาคอมไพล์:

sqlx::migrate!("../../migrations")

ไฟล์การย้ายข้อมูลอยู่ในไดเรกทอรีรากของพื้นที่เก็บข้อมูล migrations/ และทำงานโดยอัตโนมัติเมื่อเริ่มต้นระบบ sqlx-cli นั้นไม่จำเป็น

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

export DATABASE_URL='postgres://luci:luci@127.0.0.1:5432/luci'
export AUDIT_ENCRYPTION_KEY="$(python -c 'import base64, secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())')"
cargo run -p exchange -- --listen 127.0.0.1:8080

ใน PowerShell ให้ตั้งค่าตัวแปรสภาพแวดล้อมก่อน:

$env:DATABASE_URL = "postgres://luci:luci@127.0.0.1:5432/luci"
$env:AUDIT_ENCRYPTION_KEY = python -c "import base64, secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())"
cargo run -p exchange -- --listen 127.0.0.1:8080

หากไบนารี่รีลีสถูกสร้างขึ้นแล้ว ให้แทนที่ cargo run -p exchange -- ด้านบนด้วย ./target/release/exchange ที่อยู่การฟังเริ่มต้นคือ 0.0.0.0:8080; ผูกกับ 127.0.0.1 อย่างชัดเจนสำหรับการดีบักในเครื่อง

เมื่อฐานข้อมูลไม่มีบัญชีตัวดำเนินการที่เปิดใช้งาน การเริ่มต้นระบบจะบู๊ตผู้ดูแลระบบและพิมพ์โทเค็นในบันทึกการเริ่มต้นระบบนั้นเท่านั้น ข้อความธรรมดาปรากฏขึ้นหนึ่งครั้ง คำแนะนำในการปรับใช้ Reverse-proxy และบัญชีที่สมบูรณ์อยู่ในที่เก็บ docs/deployment.md หน้านั้นมีที่อยู่เซิร์ฟเวอร์และไม่ได้เผยแพร่บนเว็บไซต์นี้

การตรวจสอบก่อนกระทำการ

รันการตรวจสอบเหล่านี้จากรูทของที่เก็บ สำหรับการเปลี่ยนแปลง Rust ให้เริ่มต้นด้วยการทดสอบลังแบบโฟกัส จากนั้นตรวจสอบพื้นที่ทำงานให้เสร็จสิ้น หากการตรวจสอบการจัดรูปแบบพบว่าการเลื่อนที่มีอยู่ไม่เกี่ยวข้อง ให้จัดรูปแบบเฉพาะไฟล์ที่เปลี่ยนแปลง แทนที่จะฟอร์แมตโค้ดอื่น Android ส่วนขยายเบราว์เซอร์และคอนโซลมือถือยังต้องมีการสร้างและการทดสอบของตัวเองด้วย การทดสอบ Rust ไม่ครอบคลุมพื้นผิวเหล่านั้น

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

ดูแลรักษาเอกสาร

ตรวจสอบพฤติกรรมการใช้งานก่อนอัปเดตคำแนะนำที่เก็บข้อมูลใน docs/ หัวข้อของเว็บไซต์มีแหล่งอ้างอิงที่ website/docs/<topic>.md และงานแปลเก้าฉบับที่ website/docs/content/<locale>/<topic>.md รักษาคำสั่ง ฟิลด์ ตัวอย่างโค้ด และระดับส่วนหัวให้สอดคล้องกัน สร้างหน้าและดัชนีการค้นหาด้วยสคริปต์ แทนที่จะแก้ไข HTML เพียงอย่างเดียว รันสิ่งต่อไปนี้จากรูทของที่เก็บโดยติดตั้ง Python 3.11+, markdown-it-py และ Node.js:

python -m pip install markdown-it-py
python scripts/build-docs.py
python scripts/build-docs.py --check
python scripts/test-docs.py
python scripts/test-docs-markdown.py
node scripts/test-docs-locale.js
python scripts/test-build-docs.py
python scripts/test-site-seo.py

การตรวจสอบการสร้างยังเปรียบเทียบทุกไบต์ของไฟล์ที่สร้างขึ้นด้วยไบต์ ความล้มเหลวในเอาต์พุตที่หายไปหรือเก่าโดยไม่ต้องเขียนไฟล์ CI รันมันก่อนที่จะสร้างใหม่

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

เอกสารที่เกี่ยวข้อง

• ภาพรวมทางเทคนิค: การเชื่อมต่อขาออก การแปลเซสชัน ยุค คิวที่มีขอบเขต และการจัดเก็บโทเค็น
• Usage: ล็อกอิน, การเพิ่มอุปกรณ์, การสตาร์ท Agent, คำสั่ง และเชลล์
• คู่มือการปรับใช้: พื้นที่เก็บข้อมูล docs/deployment.md (ประกอบด้วยที่อยู่เซิร์ฟเวอร์ ไม่ได้เผยแพร่บนเว็บไซต์นี้)
• โปรโตคอลแบบใช้สาย
• การปรับใช้อุปกรณ์หลายแพลตฟอร์ม