การติดตั้ง

ภาษาอังกฤษ · Русский · ภาษายูเครน · Español · Português (Brasil) · ภาษาตุรกี · العربية · فارسی · اردو · हिन्दी · ภาษาอินโดนีเซีย · Tiếng Việt · ภาษาจีนตัวย่อ

เลือกวิธีการติดตั้ง#

สำหรับแพ็กเกจแบบพกพา ให้สกัดไฟล์TgWitness-<version>-windows-amd64-portable.zipจาก GitHub Releases สำหรับวิธีอื่น ๆ ให้ดาวน์โหลดและสกัดไฟล์ ZIP แหล่งที่มา หรือคัดลอก repository แล้วเรียกใช้คำสั่งต่อไปนี้จากไดเรกทอรีของโครงการ:

สำหรับเซิร์ฟเวอร์คลาวด์ที่ฝ่ายที่สามสามารถตรวจสอบได้ — ซึ่งสร้างขึ้นผ่าน API ของผู้ให้บริการ โดยไม่ใช้ SSH และเข้าถึงได้เฉพาะผ่าน Cloudflare Tunnel — ดู การปรับใช้ระดับความมั่นใจสูง

เมื่อเริ่มต้นระบบจะสร้าง.venvส่วนตัวและติดตั้งส่วนประกอบที่จำเป็น Docker จะสร้างส่วนประกอบเหล่านี้ภายในภาพ (image) โดยไม่จำเป็นต้องใช้ Python ของเครื่องโฮสต์ การตั้งค่าครั้งแรก จำเป็นต้องมีการเชื่อมต่ออินเทอร์เน็ต เมื่อไม่พบ Python 3.11+ ระบบStart.cmd จะขอความยินยอมก่อน ติดตั้ง Python 3.12 สำหรับผู้ใช้ Windows ปัจจุบัน (ผ่าน winget หรือตัวติดตั้งจาก python.org หลังจากตรวจสอบลายเซ็นของ Python Software Foundation); ระบบจะไม่ขอ สิทธิ์ผู้ดูแลระบบ Docker และบริการระบบปฏิบัติการยังคงเป็นข้อกำหนดเบื้องต้น

การติดตั้งแบบเนทีฟและแบบพกพาใช้ data/live ภายในโฟลเดอร์ของตัวเอง Docker ใช้โวลุ่มที่ตั้งชื่อว่า tgwitness-data ที่ /data การติดตั้งเหล่านี้เป็นระบบที่แยกกันจนกว่าคุณจะย้าย ไดเรกทอรีข้อมูลทั้งหมดอย่างตั้งใจ อย่าคาดหวังว่าคอนเทนเนอร์ Docker ใหม่จะค้นพบบัญชีแบบเนทีฟ ได้โดยอัตโนมัติ

ข้อกำหนดการติดตั้ง#

การติดตั้งแบบเนทีฟต้องการ Python 3.11 หรือเวอร์ชันใหม่กว่า พร้อมด้วย venv และ ensurepip, การเข้าถึงอินเทอร์เน็ต สำหรับการติดตั้งความพึ่งพาแรก และไดเรกทอรีโครงการที่สามารถเขียนได้สำหรับ .venv แผงควบคุมที่มาพร้อมชุดไม่ต้องการ Node.js หรือการสร้างส่วนหน้า (frontend) ให้เรียกใช้โปรแกรมเริ่มต้นจาก บัญชีระบบปฏิบัติการปกติของคุณ; TgWitness ไม่ต้องการสิทธิ์ผู้ดูแลระบบ/root

• Windows: Start.cmd ตรวจสอบ py -3 ก่อน แล้ว python ต่อ ตามด้วยโฟลเดอร์ติดตั้งตามค่าเริ่มต้นของผู้ใช้แต่ละคนและ โฟลเดอร์ Program Files และต้องการเวอร์ชัน 3.11 หรือใหม่กว่า หากไม่มีอันใดทำงานได้ มัน จะเสนอการติดตั้งอัตโนมัติตามผู้ใช้แต่ละคนตามที่อธิบายไว้ข้างต้น py -3 start.py ก็ทำงานได้เช่นกัน แพ็กเกจแบบพกพาไม่ต้องการ Python เลย
• Linux: start.sh จะลอง python3.13, python3.12, python3.11, python3 และ python แล้วแสดงคำสั่งติดตั้งสำหรับ apt, dnf, pacman, zypper, apk หรือ Homebrew เมื่อไม่มีตัวเลือกใดที่ตรงกัน การติดตั้งบน Debian/Ubuntu อาจจำเป็นต้องใช้แพ็กเกจ python3-venv ที่ตรงกับตัวแปลภาษาที่เลือก Python ค่าเริ่มต้นที่เก่าของระบบปฏิบัติการต้องถูกแทนที่หรือเสริมด้วย Python 3.11+
• macOS: ติดตั้ง Python 3.11+ เวอร์ชันล่าสุด; อย่าสมมติว่า ตัวแปลภาษาที่ระบบปฏิบัติการจัดให้ตรงตามข้อกำหนด ใช้ python3 start.py จากไดเรกทอรีของโครงการ
• Docker: ใช้ Docker Engine/Desktop พร้อม Compose v2.20 หรือเวอร์ชันใหม่กว่า Docker Desktop ต้องใช้คอนเทนเนอร์ Linux บน Windows คอนเทนเนอร์จะติดตั้ง ไลบรารี Python ที่จำเป็นด้วยตัวเอง; ระบบโฮสต์ไม่จำเป็นต้องติดตั้ง Python แยกต่างหาก

ใช้พื้นที่จัดเก็บข้อมูลแบบถาวรในเครื่องสำหรับไดเรกทอรีข้อมูล วางแผนความจุจากข้อความ, สื่อ, การเติบโตของ WAL, การส่งออก และการสำรองข้อมูล; ไม่มีข้อกำหนดขั้นต่ำ สำหรับดิสก์/RAM ที่อิงจากหลักฐานและใช้ได้กับทุกภาระงาน สถาปัตยกรรม CPU และเวอร์ชัน Python ที่ไม่มี wheel ของ dependency ที่เข้ากันได้ อาจต้องการเครื่องมือสร้างเพิ่มเติมและ การรับรองความเหมาะสมของตนเอง "Portable" ไม่ใช่คำยืนยันถึงการสนับสนุนระบบปฏิบัติการหรือฮาร์ดแวร์แบบสากล

Windows 11/Python 3.12 ได้ผ่านการตรวจสอบในเครื่องแล้ว ส่วนการกำหนดค่าสำหรับ Linux/macOS/คอนเทนเนอร์ และ CI ได้จัดเตรียมไว้แล้ว แต่ยังไม่ได้ดำเนินการบนเครื่องโฮสต์พัฒนาการนี้ ดู VERIFICATION.md เพื่อทราบขอบเขตที่แน่นอน

คอมพิวเตอร์ท้องถิ่น#

ใช้ Start.cmd บน Windows หรือ sh start.sh บน Linux/macOS. scripts\Setup.cmd หรือ sh start.sh --setup-only จะเตรียม สภาพแวดล้อมให้พร้อมใช้งาน โปรแกรมเปิดตัวจะติดตั้งส่วนประกอบที่จำเป็นเมื่อใช้ครั้งแรก; การเปิดใช้งาน ครั้งต่อไปจะใช้สภาพแวดล้อมเดิม การเข้าถึงอินเทอร์เน็ตจำเป็นสำหรับการตั้งค่าและการเก็บรวบรวมข้อมูล Telegram, แต่การดูบันทึกที่มีอยู่และการสร้างไฟล์ส่งออกสามารถทำได้แบบออฟไลน์

เรียกใช้ python start.py --check หลังจากติดตั้งเพื่อตรวจสอบการพึ่งพาในระบบท้องถิ่น Ed25519, พื้นที่จัดเก็บข้อมูล การตั้งค่ากุญแจ และที่อยู่รับฟัง โดยไม่ต้องเริ่มทำงานของตัวเก็บข้อมูล ใช้ --json เพื่อรับผลลัพธ์ที่มีโครงสร้าง ส่งค่า --data-dir, --host และ --port ที่ต้องการ การตรวจสอบนี้ไม่ติดตั้งแพ็กเกจ ไม่สร้างบันทึก และไม่เชื่อมต่อ Telegram; นี่ไม่ใช่การตรวจสอบความสมบูรณ์หรือความครอบคลุม ระบบจะตรวจสอบ บันทึกที่มีอยู่แยกต่างหาก python start.py --help ยังหลีกเลี่ยงการติดตั้งด้วย

ตัวเลือก:

หลังจากใช้ start.py แล้ว ให้เรียกใช้คำสั่งเสริมด้วย .venv\Scripts\python.exe บน Windows หรือ .venv/bin/python บน Linux/macOS หรือเปิดใช้งานสภาพแวดล้อมนั้นก่อน ตัวอย่าง python -m ... ด้านล่างนี้สมมติว่าสภาพแวดล้อมดังกล่าวได้เปิดใช้งานแล้ว

python -m tgwitness --data-dir /path/to/private/data --host 127.0.0.1 --port 8787

ตัวแปรสภาพแวดล้อม: TGWITNESS_DATA, TGWITNESS_HOST, TGWITNESS_PORT, TGWITNESS_TOKEN. TGWITNESS_VAULT_KEY_FILE เลือกโหมดกุญแจภายนอกสำหรับการติดตั้งใหม่; ดูด้านล่าง TGWITNESS_TOKEN หากกำหนดไว้ ต้องมีอย่างน้อย 24 ตัวอักษร; ใช้ค่าสุ่ม ทางเข้ารหัส หากไม่กำหนด แอปจะสร้างโทเค็นสุ่ม 256 บิตในไฟล์ panel-token.txt การกำหนดค่าสภาพแวดล้อมใหม่จะไม่เขียนทับไฟล์ดังกล่าว ให้รีสตาร์ทเพื่อหมุนเวียนข้อมูลรับรอง

มีเพียงกระบวนการเดียวเท่านั้นที่สามารถเป็นเจ้าของไดเรกทอรีข้อมูลได้ ระบบล็อกไฟล์ข้ามแพลตฟอร์มของระบบปฏิบัติการจะป้องกัน การเขียนข้อมูลพร้อมกันโดยไม่ได้ตั้งใจ ให้ใช้ Uvicorn worker เพียงหนึ่งตัว แผงควบคุมสามารถจัดการพื้นที่ทำงานได้ไม่จำกัด โดยมีไดเรกทอรีพื้นที่ทำงานเพิ่มเติมอยู่ภายใต้ profiles/<id>/. สำหรับอินสแตนซ์บริการที่แยกกัน ให้ใช้ไดเรกทอรีและพอร์ตที่ต่างกัน ไฟล์ WAL ของ SQLite ต้องเก็บไว้ในพื้นที่จัดเก็บข้อมูลถาวร แบบท้องถิ่น ไม่ใช่ในระบบไฟล์เครือข่าย อย่าใช้โวลุ่มเดียวกันระหว่างรีพลิกา

แพ็กเกจแบบพกพาสำหรับ Windows#

ทุกเวอร์ชันที่เผยแพร่บน GitHub จะประกอบด้วย TgWitness-<version>-windows-amd64-portable.zip และ .sha256 ซึ่งประกอบด้วย Python 3.12 เวอร์ชันรันไทม์อย่างเป็นทางการที่สามารถฝังได้จาก python.org (ค่า checksum ถูกตรึงไว้ใน tools/build_portable.py), TgWitness และไลบรารีที่จำเป็นซึ่งถูกตรึงไว้, รวมถึงตัวเปิดใช้งานสามตัว:

แตกไฟล์อาร์ไคฟ์ทั้งหมดไปยังโฟลเดอร์ที่สามารถเขียนได้ เช่น Documents\TgWitness; อย่า เรียกใช้จากภายในไฟล์ ZIP หรือจากโฟลเดอร์ Program Files เนื่องจากระบบรันไทม์ใช้เส้นทางโมดูลที่แยกออกมา ดังนั้นการติดตั้ง Python อื่น ๆ และ PYTHONPATH จึงไม่ส่งผลต่อมัน ข้อมูลจะเก็บอยู่ใน โฟลเดอร์ data ของแพ็กเกจ เพื่ออัปเดต ให้หยุด TgWitness ก่อน จากนั้นแตกไฟล์เวอร์ชันใหม่ไปยัง โฟลเดอร์ใหม่ และคัดลอกโฟลเดอร์ data ไปยังโฟลเดอร์เดิม

ติดตั้งด้วยตัวเองบน Windows 64-bit ด้วย Python 3.12:

python tools/build_portable.py

ตัวสร้างจะตรวจสอบค่า checksum ขณะทำงาน ติดตั้งการพึ่งพาที่จำกัดลงใน แพ็กเกจ ดำเนินการตรวจสอบความพร้อมด้วยตัวแปลภาษาที่ฝังไว้ และเขียนไฟล์ ZIP พร้อมค่า checksum ลงใน dist/

Container#

docker compose up -d --build --wait

สิ่งนี้สร้าง volume ที่มีชื่อและคงที่สำหรับ /data พอร์ตเว็บถูกแมปไปยัง 127.0.0.1:8787. กระบวนการนี้ทำงานด้วย UID 10001 พร้อม ความสามารถที่ถูกจำกัด ระบบไฟล์รูทแบบอ่านอย่างเดียว และ /data และ /tmp ที่สามารถเขียนได้ --wait ตรวจสอบสภาพการทำงานของเว็บเซิร์ฟเวอร์ก่อนที่จะส่งคืนผลลัพธ์; มันไม่ดำเนินการ การอนุญาตหรือการส่งข้อความ Telegram ตัวช่วยที่จัดเตรียมไว้ใช้เวลารอความพร้อม 180 วินาที หลังการสร้างระบบ การดาวน์โหลดความพึ่งพาเริ่มต้นอาจใช้เวลานานกว่านั้น

ไฟล์ Compose ฐานทั้งสองใช้ชื่อโครงการ tgwitness ดังนั้นการสกัดเวอร์ชันใหม่ ไปยังไดเรกทอรีอื่นจะไม่เลือกโวลุ่มข้อมูลใหม่โดยอัตโนมัติ ให้รักษาการปรับใช้ เพียงหนึ่งเดียวที่ทำงานอยู่สำหรับโครงการนั้น สำหรับการติดตั้งแบบอิสระ ให้ใช้ docker compose -p NAME ... ที่ไม่ซ้ำกันและพอร์ตโฮสต์ที่ต่างกัน และรักษาทั้งสองไว้เมื่อมีการอัปเดต สำหรับการปรับใช้เวอร์ชันเก่าที่ใช้ชื่อโครงการต่างออกไป ให้ใช้ชื่อเดิม ร่วมกับ -p; docker compose ls จะแสดงรายการโครงการที่มีอยู่

คัดลอก deploy/env.example ไปยัง .env และเปลี่ยน TGWITNESS_PORT เพื่อใช้พอร์ต loopback ที่ต่างกัน ตัวอย่างเช่น TGWITNESS_PORT=8788 เปิดแผงควบคุมที่ http://127.0.0.1:8788; คอนเทนเนอร์ยังคงรับฟังที่พอร์ต 8787 .env ถูก Git-ignored

รับโทเค็นเริ่มต้น:

docker compose exec tgwitness cat /data/panel-token.txt

คำสั่งที่มีประโยชน์:

docker compose ps
docker compose logs --tail 100 -f
docker compose stop
docker compose up -d --wait

restart: unless-stopped จะรีสตาร์ทตัวเก็บข้อมูลหลังจากเกิดข้อผิดพลาดหรือเมื่อ Docker daemon รีสตาร์ท บนเซิร์ฟเวอร์ Linux ให้เปิดใช้งาน Docker เมื่อบูตระบบโดยใช้ผู้จัดการบริการ ของระบบปฏิบัติการของคุณ ซึ่งโดยทั่วไปคือ sudo systemctl enable --now docker บน Windows/macOS ให้เปิดใช้งาน การตั้งค่า "เริ่มเมื่อลงชื่อเข้าใช้" ของ Docker Desktop การออกจากระบบเดสก์ท็อป การเข้าสู่โหมดสลีป หรือ Docker daemon ที่ถูกหยุด สามารถขัดขวางการเก็บข้อมูลได้ คอนเทนเนอร์ที่ถูกหยุดอย่างชัดเจนจะยังคง อยู่ในสถานะหยุดจนกว่าคุณจะเริ่มมันขึ้นใหม่

ในตัวอย่างการกำหนดค่านี้ ปริมาณ /tmp ถูกจำกัดไว้ที่ 512 MiB การสร้างไฟล์ส่งออก จะใช้temporary-exports/ ของแต่ละพื้นที่ทำงานบน /data ที่คงอยู่แทน ให้สำรองพื้นที่ ไว้ที่นั่นสำหรับการส่งออกพร้อมกัน การขยายตัวของ journal/WAL ไฟล์สื่อ และการสำรองข้อมูล ตัวเรียกใช้งาน (launcher) ใช้ deploy/constraints.txt เพื่อกำหนดเวอร์ชันที่ผ่านการรับรองของ dependency ใน runtime Docker และเซิร์ฟเวอร์ระดับความมั่นใจสูงจะติดตั้งจาก deploy/requirements.lock และ deploy/build.lock ด้วย pip --require-hashes: ทุกไฟล์แพ็กเกจต้องตรงกับ SHA-256 ที่บันทึกไว้ใน commit ดังนั้นไฟล์ที่ถูกแทนที่บน PyPI หรือมิเรอร์จะถูกปฏิเสธ ภาพพื้นฐานของ Python และแพ็กเกจระบบปฏิบัติการยังคงต้องผ่านการรับรองเวอร์ชันอย่างอิสระ

อย่าใช้คำสั่ง `docker compose down -v` เว้นแต่คุณมีเจตนาที่จะทำลายบันทึกและกุญแจ รายงานสภาพคอนเทนเนอร์แสดงถึงความพร้อมใช้งานของเว็บเซิร์ฟเวอร์ ไม่ใช่การจับข้อมูล Telegram ที่สำเร็จ ตรวจสอบสถานะของตัวเก็บข้อมูลบนแผงควบคุม สัญญาณชีพ ความผิดพลาด และเหตุการณ์การครอบคลุม

โปรไฟล์ผู้เป็นพยานอิสระ#

บริการ witness (แบบเลือกใช้) ทำงานเป็นพยานอิสระใน คอนเทนเนอร์ของตัวเอง พร้อมด้วยกุญแจและบันทึกของตัวเองในโวลุ่ม witness-data และ โทเค็นพยานแบบอ่านอย่างเดียวสำหรับตัวเก็บข้อมูล สร้างโทเค็นบนหน้า Witness ของแผงควบคุม เพิ่ม โทเค็นบอทและช่องไปยัง .env แล้วเริ่มโปรไฟล์:

docker compose --profile witness up -d          # deploy/compose/compose.image.yaml: same flag
docker compose logs witness                     # witness key fingerprint

บริการนี้ติดต่อกับผู้เก็บข้อมูลภายในเครือข่าย Compose ที่ http://tgwitness:8787 (TGWITNESS_WITNESS_COLLECTOR จะแทนที่มัน เช่น /profiles/<workspace ID> สำหรับ พื้นที่ทำงานอื่น) สำหรับ witness บนเซิร์ฟเวอร์แยกต่างหาก ที่ดำเนินการโดยบุคคลอื่น ให้ใช้ deploy/compose/compose.witness.yaml ที่นั่น โดยตั้งค่า TGWITNESS_WITNESS_COLLECTOR เป็นที่อยู่ HTTPS ของผู้เก็บข้อมูล; ไฟล์ดังกล่าวมีเพียง witness เท่านั้น

ติดตั้งภาพระบบที่เผยแพร่แล้ว#

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

คัดลอก deploy/env.example ไปยัง .env ตั้งค่า TGWITNESS_IMAGE เป็นเวอร์ชันที่เผยแพร่ โดยใช้ เส้นทางรีโพสิตอรีแบบตัวพิมพ์เล็ก เช่น:

TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.7.0
TGWITNESS_PORT=8787

รันไฟล์นี้ด้วยตัวเอง แทนที่จะใช้compose.yaml:

docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait
docker compose --project-directory . -f deploy/compose/compose.image.yaml exec tgwitness cat /data/panel-token.txt

ไม่จำเป็นต้องติดตั้งแหล่งโค้ดต้นฉบับ Python หรือคอมไพเลอร์บนเครื่องโฮสต์ กระบวนการปล่อยเวอร์ชัน มุ่งเป้าไปที่คอนเทนเนอร์ Linux AMD64 และ ARM64 รวมถึงเครื่องเสมือน Linux ของ Docker Desktop ใช้แท็กเวอร์ชันหรือ ghcr.io/owner/repository@sha256:... จากสรุปขั้นตอนการทำงาน ไม่มีการกำหนดค่าแท็ก latest ที่เคลื่อนย้ายได้ หรือการอัปเกรดแอปพลิเคชันแบบอัตโนมัติ ตัว ภาพและตัวแปรแหล่งที่มาใช้ปริมาณข้อมูลเดียวกันเมื่อชื่อโครงการตรงกัน

HTTPS อัตโนมัติบนเซิร์ฟเวอร์#

ใช้เซิร์ฟเวอร์ที่มี Docker, โดเมนที่คุณควบคุมได้ และพื้นที่จัดเก็บข้อมูลท้องถิ่นแบบถาวร กำหนดให้บันทึก A/AAAA ของโดเมนชี้ไปยังเซิร์ฟเวอร์; เผยแพร่ AAAA เฉพาะเมื่อ IPv6 สามารถเข้าถึง เซิร์ฟเวอร์ได้เท่านั้น เปิดพอร์ต TCP 80 และ 443 สำหรับการรับข้อมูลเข้า และเปิด DNS/HTTPS สำหรับการส่งข้อมูลออกเพื่อการออกใบรับรอง บริการอื่น ๆ ต้องไม่ใช้พอร์ตเหล่านี้อยู่แล้ว

คัดลอก deploy/env.example ไปยัง .env และกำหนดชื่อโฮสต์ โดยไม่รวมสคีมาหรือเส้นทาง:

TGWITNESS_DOMAIN=watch.your-domain.org

เริ่มสร้างจากแหล่งต้นแบบด้วย HTTPS overlay:

docker compose -f compose.yaml -f deploy/compose/compose.https.yaml up -d --build --wait
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml exec tgwitness cat /data/panel-token.txt

docker compose --project-directory . -f deploy/compose/compose.image.yaml -f deploy/compose/compose.https.yaml up -d --wait

สำหรับภาพที่เผยแพร่ ให้ใช้ deploy/compose/compose.image.yaml เป็นไฟล์แรกแทน ให้เก็บ อาร์กิวเมนต์ -f ทั้งสองไว้สำหรับคำสั่ง status, logs, update และ stop ในภายหลัง

Caddy รับและต่ออายุใบรับรอง, เปลี่ยนเส้นทาง HTTP เป็น HTTPS, และส่งต่อ คำขอไปยังตัวเก็บข้อมูลบนเครือข่าย Compose ส่วนตัว สถานะของใบรับรองมี โวลุ่มถาวรเป็นของตัวเอง พอร์ตโฮสต์โดยตรงของตัวเก็บข้อมูลยังคงเป็น loopback เท่านั้น การตั้งค่า Caddy ที่ให้มาไม่เปิดใช้งานการบันทึกการเข้าถึง

เปิด https://watch.your-domain.org และป้อนโทเค็นของแผงควบคุม การเตรียมความพร้อม ไม่ยืนยันการออกใบรับรองหรือความสามารถในการเข้าถึงจากภายนอก หาก HTTPS ยัง ไม่พร้อม ให้ตรวจสอบ DNS กฎไฟร์วอลล์ และ:

docker compose -f compose.yaml -f deploy/compose/compose.https.yaml logs --tail 100 caddy

ภาพ Caddy ที่ให้มาจะตามแท็ก 2-alpine ของมัน การดึงข้อมูลจะอัปเดตภาพนั้น; หากต้องการเวอร์ชันโครงสร้างพื้นฐานที่คงที่ ให้ปักหมุด digest ที่ผ่านการทดสอบแล้วในระบบของคุณ

การอัปเดตและการสำรองข้อมูล#

รักษาชื่อโครงการ Compose และปริมาณข้อมูลให้คงเดิมระหว่างการอัปเดต ก่อนอื่นให้หยุด ตัวเก็บข้อมูล (collector) และสร้างสำเนาสำรองอย่างครบถ้วน สำหรับการติดตั้งแบบอิงแหล่งที่มา (source-based deployment) ตามค่าเริ่มต้น:

docker compose stop
docker compose cp tgwitness:/data ../tgwitness-backup-before-update

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

สำหรับการติดตั้งจากแหล่งต้นทาง ให้ดาวน์โหลดไฟล์เวอร์ชันใหม่และรันคำสั่งต่อไปนี้:

docker compose up -d --build --wait

สำหรับการติดตั้งแบบภาพ ให้เปลี่ยน TGWITNESS_IMAGE เป็นเวอร์ชันที่ต้องการ แล้วรันคำสั่ง:

docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait

ใช้ไฟล์ Compose ของการติดตั้งของคุณสำหรับคำสั่ง stop/copy ข้างต้นด้วย รักษา .env, การตั้งค่าแบบกำหนดเอง และชื่อโครงการให้เหมือนเดิม down เก็บ volumes ที่มีชื่อไว้; down -v ลบพวกมันออก อย่าคัดลอก .venv ระหว่างระบบปฏิบัติการ หรือเวอร์ชัน Python สำหรับการอัปเดตแบบเนทีฟ ให้หยุด TgWitness สำรองข้อมูล ไดเรกทอรีข้อมูลทั้งหมด เปลี่ยนไฟล์ต้นฉบับ และรัน python start.py --setup-only ก่อนเปิดใช้งาน

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

การปล่อยเวอร์ชันอัตโนมัติบน GitHub#

กระบวนการปล่อยเวอร์ชันจะพร้อมใช้งานทันทีหลังจาก โครงการนี้ถูกส่งไปยัง repositori GitHub ที่เปิดใช้งาน Actions แล้ว ระบบจะทำงานเมื่อ GitHub Release ถูกเผยแพร่ รวมถึงเวอร์ชันก่อนปล่อย (prerelease) การส่งร่าง (drafts) และการส่งแท็ก (tag pushes) เพียงอย่างเดียวจะไม่เผยแพร่แพ็กเกจ

1. กำหนดเวอร์ชันแพ็กเกจและบันทึกการเปลี่ยนแปลง (changelog) แล้วเผยแพร่เวอร์ชันที่ติดแท็กด้วย v พร้อมทั้งเวอร์ชัน pyproject.toml ที่ถูกต้อง เช่น v0.7.0.
2. กระบวนการทำงานนี้จะตรวจสอบความถูกต้องของแท็กและดำเนินการตรวจสอบ Python ที่ใช้ร่วมกันบน Windows/Linux/macOS, general/account-import/QR browser, source-package และ Docker การติดตั้งแบบเนทีฟใหม่ยัง ได้รับการทดสอบบนระบบปฏิบัติการทั้งสามโดยใช้ Python 3.12
3. เมื่อการตรวจสอบดังกล่าวผ่านแล้ว ระบบจะทำการทดสอบเบื้องต้น (smoke test) ภาพระบบ ARM64 บน QEMU, เผยแพร่ ภาพระบบ AMD64/ARM64 ไปยัง ghcr.io/<lowercase-owner>/<lowercase-repository>:<version>, และแนบไฟล์ ZIP แหล่งที่มา, ค่า checksum และไฟล์ Python wheel ไปยังการปล่อยเวอร์ชัน ส่วนงานแยกต่างหาก บน Windows จะทำการสร้างและแนบไฟล์ ZIP แบบพกพาพร้อมค่า checksum ของมัน
4. หลังการเผยแพร่ครั้งแรก ให้เปิดการตั้งค่าแพ็กเกจ GHCR และตั้งการมองเห็น เป็น Public หากมีวัตถุประสงค์ที่จะดึงภาพแบบไม่ระบุตัวตน การมี repositori แหล่งที่มาแบบสาธารณะ เพียงอย่างเดียวไม่รับประกันว่าแพ็กเกจคอนเทนเนอร์จะเป็นแบบสาธารณะ นโยบายขององค์กรต้อง อนุญาตให้เผยแพร่แพ็กเกจได้ กระบวนการทำงานนี้ใช้ GITHUB_TOKEN; ไม่ควรมี รหัสผ่านของ registry หรือข้อมูลรับรอง VPS ใน repositori

ความสำเร็จของกระบวนการทำงานจากระยะไกลยังไม่ได้รับการยืนยันจากการเตรียมการในระบบท้องถิ่นนี้ การจำลอง ARM64 เป็นการตรวจสอบเบื้องต้น (smoke check) ไม่ใช่การรับรองการทำงานบนฮาร์ดแวร์ต้นฉบับหรือการรับรอง Telegram ในสภาพแวดล้อมจริง สิ่งนี้ช่วยอัตโนมัติในการแพ็กเกจเวอร์ชันใหม่; การเริ่มต้นเซิร์ฟเวอร์ยังคงต้องใช้คำสั่ง Compose และข้อกำหนดเบื้องต้นเกี่ยวกับโดเมน/โฮสต์ เซิร์ฟเวอร์ที่มีอยู่จะไม่ถูกอัปเกรด หรือรีสตาร์ทโดยอัตโนมัติเมื่อมีเวอร์ชันใหม่ถูกเผยแพร่

เซิร์ฟเวอร์ระยะไกล#

ให้บริการนี้ผูกกับ loopback และใช้ SSH tunnel หรือยุติ HTTPS ที่ proxy กลับด้าน ไฟล์ Compose พื้นฐานใช้ได้เฉพาะในเครื่องท้องถิ่นเท่านั้น; ส่วน overlay deploy/compose/compose.https.yaml ที่เป็นตัวเลือกจะจัดหา Caddy สำหรับโดเมนที่ตั้งค่าไว้ อย่าให้โทเค็น bearer ปรากฏใน URL และบันทึกพร็อกซี พร็อกซีแบบย้อนกลับควรจำกัด ขนาดคำขอและอัตราการเชื่อมต่อ อย่าเปิดเผย HTTP แบบธรรมดาต่ออินเทอร์เน็ต

ตัวอย่างสำหรับ systemd, งานล็อกอิน Windows, ตัวแทนผู้ใช้ macOS และ Caddy มีให้ ในโฟลเดอร์ deploy/. โปรดตรวจสอบ/ปรับเปลี่ยนเส้นทางของพวกมันก่อนการติดตั้ง พวกมันเป็นแม่แบบที่จัดเตรียมไว้ ไม่ใช่คุณสมบัติของแพลตฟอร์มที่ทำงานในเครื่องท้องถิ่น ไม่มี บริการพื้นหลังหรืองานใดที่ถูกลงทะเบียนโดยตัวเปิดใช้งานปกติ

บน Windows การเปิดpythonw.exe แบบไม่มีหน้าต่างจะเก็บข้อมูลวินิจฉัยการเริ่มต้นระบบ/เซิร์ฟเวอร์ไว้ใน logs/server.log ภายในไดเรกทอรีข้อมูล (5 MiB ต่อไฟล์, สำรองข้อมูลแบบหมุนเวียนสองชุด) การเปิดผ่านคอนโซลจะเก็บบันทึกคอนโซลไว้ การบันทึกการเข้าถึง HTTP ถูกปิดใช้งานในทั้งสอง โหมด ปกป้องบันทึกข้อมูลด้วยไดเรกทอรีข้อมูลและตรวจสอบก่อนที่จะแบ่งปัน

การเริ่มต้นใหม่และช่องว่าง#

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

StringSession เก็บรักษาการอนุญาต แต่ไม่เก็บสถานะการอัปเดต/เอนทิตีแบบคงทนของ Telethon หน้าสนทนาจะถูกโหลดใหม่เมื่อเริ่มต้น Telegram/Telethon สามารถกู้คืนการขัดจังหวะการส่งข้อมูลบางส่วน ระหว่างการทำงานได้ แต่ TgWitness ไม่รับประกันการเล่นซ้ำแบบคงทนเมื่อรีสตาร์ทกระบวนการ ทุกครั้งที่เริ่มต้นระบบจะบันทึกส่วนหัวของบันทึกก่อนหน้าและขอบเขตออฟไลน์ ตัวตรวจสอบจะตรวจสอบการเชื่อมต่อทุก 10 วินาที และเพิ่มสัญญาณชีพทุกนาที (พารามิเตอร์ → Liveness record every). การขัดจังหวะสั้นๆ อาจถูกมองข้ามได้; การเชื่อมต่อที่เสถียรไม่รับประกันการส่งข้อมูลอัปเดต อย่างครบถ้วน ภาพถ่าย (Snapshots) เป็นการสังเกตประวัติปัจจุบันอย่างชัดเจน ไม่เคยเป็นการซ่อมแซมช่องว่าง

คิวสื่อถูกเก็บไว้ในฐานข้อมูล SQLite ของแต่ละพื้นที่ทำงาน ข้อความและงานที่เกี่ยวข้อง จะถูกบันทึกแบบอะตอมิก งานที่กำลังทำงานอยู่แต่ถูกขัดจังหวะจะได้รับการกู้คืนเพื่อลองใหม่เมื่อเริ่มต้นใหม่ การดาวน์โหลดแต่ละครั้งมีเวลาหมดอายุพื้นฐาน 120 วินาที บวกกับเวลาตามความเร็ว 256 KiB/s ตามขนาดไฟล์ และ ขีดจำกัด 1–2,000 MiB ต่อประเภทไฟล์แนบ; เวลาหมดอายุ ความเร็ว และการลองใหม่ ตั้งอยู่ในส่วน Parameters ผู้รวบรวม จะข้ามไฟล์ที่มีขนาดไม่ทราบ การหยุดชั่วคราวจะเก็บงานในคิวไว้ การลองใหม่จะใช้ ตัวระบุไฟล์ที่สังเกตได้เดิม ไม่เคยใช้เวอร์ชันล่าสุดของข้อความที่ถูกแก้ไขในภายหลัง ความล้มเหลวชั่วคราวมีการลองใหม่ที่จำกัด; การหยุดชั่วคราวของ FloodWait สำหรับสื่อจะคงอยู่หลังการเริ่มต้นใหม่ การกู้คืนสื่อแยกต่างหากจากการกู้คืนการอัปเดต Telegram และไม่สามารถสร้างไฟล์ที่หายไปใหม่ได้

การสำรองข้อมูล การกู้คืนข้อมูล และความจุ#

หยุดกระบวนการก่อนที่จะคัดลอกไดเรกทอรีข้อมูลทั้งหมด รวมถึง vault.key, signing.enc, credentials.enc, ฐานข้อมูล SQLite/ไฟล์ WAL, สื่อ, โทเค็น, จุดตรวจสอบ, และโปรไฟล์/ไดเรกทอรีย่อยทั้งหมด กู้คืน สำเนาทั้งหมดในขณะที่บริการปลายทางถูกหยุดไว้ การขาดกุญแจ vault หรือ ความไม่ตรงกันของกุญแจลงนามจะทำให้การเริ่มต้นล้มเหลว; อย่าสร้างกุญแจใหม่เพื่อบังคับการเข้าถึง

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

เริ่มต้นการตรวจสอบและส่งออกบันทึกสตรีมแทนการโหลดบันทึกทั้งหมด การส่งออกจะตรึงภาพสแนปช็อตที่อ่านได้ในขณะที่การเขียน WAL ใหม่สามารถดำเนินต่อไปได้; การส่งออกที่ใช้เวลานาน สามารถเก็บหน้า WAL ไว้ได้ ดังนั้นความจุของดิสก์ยังคงมีความสำคัญ ZIP ถูกจำกัดไว้ที่ 4 GiB เมื่อไม่ถูกบีบอัด เพื่อให้สอดคล้องกับค่าเริ่มต้นของผู้ตรวจสอบอิสระ; พารามิเตอร์ → Largest signed ZIP จะเพิ่มขีดจำกัด และไฟล์เก็บถาวรดังกล่าวจะได้รับการตรวจสอบด้วย verify.py --max-gib N รูปแบบอื่นไม่มีขีดจำกัดจำนวนเหตุการณ์ เบราว์เซอร์ที่รองรับจะสตรีมส่วนการตอบกลับไปยังไฟล์ที่ผู้ใช้เลือก เบราว์เซอร์อื่น จะบัฟเฟอร์ได้สูงสุด 128 MiB และส่งการถ่ายโอนข้อมูลที่ใหญ่กว่าไปยัง CLI ที่ได้รับการยืนยันตัวตน:

python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip

ใช้ --profile ID จาก Exports → Workspace ID สำหรับพื้นที่ทำงานอื่น, --format zip|jsonl|csv|html, --url https://your-server สำหรับเซิร์ฟเวอร์ระยะไกล หรือ --max-mib เพื่อเปลี่ยนขีดจำกัดการส่งข้อมูล 5 GiB HTTP แบบธรรมดาได้รับอนุญาตเฉพาะสำหรับ loopback เท่านั้น โทเค็นถูกส่งผ่านในส่วนหัว การเปลี่ยนเส้นทางถูกปฏิเสธ ไฟล์ที่มีอยู่ จะไม่ถูกเขียนทับ และการดาวน์โหลดที่ไม่สมบูรณ์จะไม่ถูกเผยแพร่เป็นไฟล์ที่เสร็จสมบูรณ์ หาก TGWITNESS_TOKEN เขียนทับโทเค็นที่สร้างขึ้น ให้ใช้ไฟล์ที่ได้รับการป้องกันแยกต่างหาก ซึ่งมีค่าที่ใช้งานอยู่: panel-token.txt จะไม่ถูกเขียนทับโดยการเขียนทับนี้ SHA-256 ของคำสั่งนี้เป็นเพียงค่าตรวจสอบการถ่ายโอนเท่านั้น; โปรดตรวจสอบ ZIP ที่ลงนามอย่างอิสระ

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

แผงควบคุมแสดงสื่อที่อยู่ในคิว/ล้มเหลว สื่อที่รอการประมวลผลที่เก่าที่สุด พื้นที่ดิสก์ว่าง การหยุดชั่วคราวของคำขอ Telegram และแหล่งข้อมูลที่การเข้าถึงยังไม่ได้รับการยืนยัน การวินิจฉัยเหล่านี้ไม่ใช่ ระบบตรวจสอบการส่งข้อมูลแบบ end-to-end ที่สมบูรณ์ พื้นที่ทำงานใช้กระบวนการร่วมกัน; บัญชีที่มีกิจกรรมรบกวนอาจ ยังคงส่งผลกระทบต่อบัญชีอื่นได้ กระบวนการทำงานแยกกัน การเก็บรักษา/หมุนเวียนข้อมูล การกู้คืนการอัปเดต ที่ทนทาน และการรับรองการปรับใช้อย่างเต็มรูปแบบยังคงมีอยู่ การเข้าถึงแผงควบคุมที่จำกัดขอบเขตถูกบันทึก ไว้ในส่วนการเข้าถึงและสิทธิ์; จุดตรวจสอบอิสระถูกครอบคลุมในคู่มือ ผู้เป็นพยาน

ตัวเลือกการเชื่อมต่อและการป้องกัน#

เส้นทางเชื่อมต่อถูกกำหนดตามพื้นที่ทำงาน (workspace) และควรตั้งค่าก่อนการอนุญาต SOCKS5/HTTP CONNECT ใช้ไลบรารี python-socks ที่ถูกกำหนดไว้ MTProxy ใช้ การขนส่งขั้นกลางแบบสุ่มทดลองของ Telethon; ไม่สนับสนุน Fake TLS ee secrets การเปลี่ยนไปใช้เส้นทางสำรองโดยตรงขึ้นอยู่กับโหมด IP ที่เลือก: โหมด Hide IP ไม่อนุญาต; โหมด fallback แบบชัดเจนอนุญาตหลังจากรอระยะเวลาหนึ่ง โหมด Tunnel/VPN อนุญาตเส้นทางโดยตรงแต่ไม่สร้าง VPN นี่ไม่ใช่กฎนโยบายเครือข่ายระดับระบบ

สำหรับการติดตั้งใหม่ TGWITNESS_VAULT_KEY_FILE จะชี้ไปยังไฟล์กุญแจหลักแบบสุ่ม ที่ได้รับการป้องกันแยกต่างหาก ให้ติดตั้งไฟล์นี้ในโหมดอ่านอย่างเดียว (read-only) นอกโฟลเดอร์ /data ในคอนเทนเนอร์ รักษาข้อมูลเมตาดาต้า salt ของไฟล์ vault.external.json แบบสาธารณะให้คงอยู่ โดยแยกเก็บไว้กับแต่ละพื้นที่ทำงาน (workspace) และกุญแจหลักอย่างแยกกัน Vault ท้องถิ่นที่มีอยู่จำเป็นต้องมีการย้ายข้อมูลตามแผน; การตั้งค่าตัวแปรนี้จะไม่ แปลงข้อมูลเหล่านั้นโดยอัตโนมัติ การจัดเก็บและส่งออกข้อความ/สื่อไม่ได้รับการเข้ารหัสโดยแอปพลิเคชัน ใช้โวลุ่มที่เข้ารหัสและพื้นที่จัดเก็บชั่วคราวส่วนตัวที่เพียงพอเมื่อจำเป็น

ขั้นตอนรายละเอียด: การเชื่อมต่อ/ความปลอดภัย และ โหมดการทำงาน