Rujukan / Bukti
Telegram · Saksi bebas
Jalankan witness dengan kunci dan botnya sendiri, terbitkan titik pemeriksaan yang ditandatangani ke saluran dan periksa eksport menentangnya.
TgWitness / Dokumentasi · Bukti dan pengesahan
Eksport dan sahkan · Jaminan tinggi · Panduan panel
Saksi menyimpan titik pemeriksaan yang ditandatangani secara berasingan daripada pengumpul. Ia memeriksa tandatangan pengumpul dan kesinambungan jurnal, menandatangani hasil tersebut dengan kuncinya sendiri, dan menerbitkannya ke saluran Telegram. Jalankan ia pada pelayan berasingan dengan akses baca sahaja ke hujung saksi pengumpul.
Keputusan teknikal termasuk awalan jurnal yang disimpan, respons cabaran, semakan tandatangan, semakan kemasukan/ketekalan Merkle dan hasil kesinambungan yang ditandatangani. Bagi saksi yang dikendalikan oleh penjaga lain, simpan maklumat penjaga dan rekod kawalan kunci bersama cap jarinya. Kunci berasingan dan jagaan berasingan menerangkan bahagian persediaan yang berbeza. Pengesah melaporkan bahawa kunci kedua menyimpan head jurnal dan sehingga rekod yang mana; rekod kawalan kunci penjaga menunjukkan siapa yang memegang kunci itu. Jurnal saksi ialah semakan sokongan; minimum untuk bukti ialah masa pihak ketiga. Siaran saluran menambah masa luaran: Telegram meletakkan tarikh pada setiap siaran awam, dan pengesah membaca tarikh itu sendiri.
Diagram sebagai teks
- Pengumpul → Saksi (titik pemeriksaan yang ditandatangani: jumlah rekod + hash kepala)
- Saksi → Jurnal saksi, kunci sendiri
- Saksi → Saluran Telegram (pos yang disahkan melalui botnya sendiri)
- ZIP Bukti → verify.py
- Jurnal saksi, kunci sendiri → verify.py
- Saluran Telegram → verify.py (t.me/s halaman dibaca secara langsung, atau eksport Desktop)
Pada halaman ini
Apa yang disimpan oleh saksi#
| Saksi mempunyai | Saksi tidak pernah |
|---|---|
| Token saksi baca sahaja untuk satu ruang kerja | Sesi Telegram atau kelayakan API pengumpul |
| Kunci Ed25519 dan jurnal tersendiri | Bilik perbendaharaan pengumpul, kunci tandatangan atau token panel |
| Token bot Telegramnya sendiri | Kandungan mesej: kepala ialah kiraan rekod dan hash |
Token itu dicipta di Lebih banyak alat → Ekstra → Saksi Bebas, dipaparkan sekali dan disimpan hanya sebagai SHA-256. Ia membuka tepat satu titik akhir, GET /api/witness/head, yang mengembalikan checkpoint yang baru ditandatangani serta pengira koleksi tanpa kandungan yang ditandatangani dan kesihatan operasi.
Ia tidak dapat membuka panel, membaca kandungan mesej atau menukar tetapan, dan token panel tidak diterima di sana. Batalkan token pada halaman yang sama. Pengumpul merekodkan bila kunci saksi baharu mula memeriksa (witness.seen) dan memaparkan pemeriksaan terakhir bagi setiap token; saksi yang belum memeriksa dalam tempoh 2.5 dikira lewat.
Saksi baharu menghantar cabaran rawak pada setiap undian; pernyataan tangkapan memantulkannya di bawah tandatangan pengumpul. Pengira diikat pada checkpoint tepat dan disertakan dalam kiriman saksi bertandatangan. Kepala warisan kekal diterima oleh saksi berdiri sendiri. Pertumbuhan jurnal sahaja tidak pernah dikira sebagai mesej baharu.
Apa yang diperiksa dan direkodkan#
Setiap selang (10 minit secara lalai) saksi:
- mengambil kepala itu sendiri (pengumpul tidak boleh menolaknya atau melangkauinya);
- memeriksa sahih tandatangan pengumpul, kunci pengumpul yang dipaku (
--collector-fingerprint, atau kunci pertama yang dilihat), kiraan yang tidak berkurangan dan kepala yang tidak berubah pada kiraan yang tidak berubah. Bukti inklusi Merkle dan konsistensi mengesahkan bahawa jurnal yang berkembang memanjangkan titik pemeriksaan yang disimpan. Setelah bukti kesinambungan digunakan, pemindahannya ditolak; - menambah rekod yang disahkan ke jurnalnya sendiri:
witness.anchordengan statusok,key_changed,rollback(lebih sedikit rekod berbanding sebelum ini),fork(panjang sama, kepala berbeza) atauinvalid(jawapan gagal pengesahan), atauwitness.no_responseapabila pengumpul tidak menjawab; - menyiarkan hasil ke saluran, ditandatangani, termasuk "tiada jawapan" selagi saksi sedang berjalan dan boleh mengakses Bot API. ID siaran direkodkan (
witness.posted), siaran gagal juga (witness.post_failed).
Satu pos kelihatan seperti ini; baris terakhir memuatkan kenyataan yang disahkan:
TgWitness witness #42 · journal head
Collector 3fa9c2d1e0b4a7f6: 18234 records
Head 9b1f…c07e
2026-10-28T19:40:00.123+00:00
TGW1.eyJhdCI6…<statement>.<signature>
Jalankan witness#
Anda memerlukan bot Telegram (cipta satu dengan @BotFather), sebuah saluran di mana bot tersebut adalah pentadbir, dan alamat pengumpul yang boleh diakses oleh saksi — melalui HTTPS di luar rangkaian persendirian (lihat profil HTTPS dalam penyebaran).
Buka Alat Lain → Tambahan → Saksi Bebas → Konfigurasikan
di panel. Tiga langkah merangkumi akses baca sahaja, saluran dan selang anda, kemudian melancarkan saksi. Dasar penerbitan, proksi HTTP/SOCKS5 pilihan dan alamat Bot API tersuai berada di bawah Tetapan Lanjutan
. Borang memuat turun witness.json
dengan kunci pengumpul ruang kerja ini dipin. Muat turun token baca-sahaja yang baru dicipta dengan menyimpan fail akses
sebagai witness-token.txt
; letakkan fail itu dan bot-token.txt
yang dicipta pada hos saksi di sebelah JSON tersebut. Pengumpul tidak pernah menerima token bot.
Pemuat turunan tidak memulakan sebarang perkhidmatan atau menyiarkan sebarang mesej. Tiada saksi projek yang dihoskan didaftarkan secara tersirat.
python -m tgwitness.witness run --config witness.json --check-config
python -m tgwitness.witness run --config witness.json
python -m tgwitness.witness fingerprint --config witness.json
Perintah pertama memeriksa konfigurasi dan fail rahsia tanpa permintaan rangkaian atau penciptaan kunci. Laluan dalam JSON adalah relatif kepada fail tersebut; laluan CLI/persekitaran adalah relatif kepada direktori kerja. Simpan cap jari saksi di luar hosnya. Penunjuk tinjauan terakhir pengumpul hanya mengesahkan permintaan; penerbitan dilaporkan oleh Bukti atau disemak dalam jurnal saksi dan saluran.
Jika panel diletakkan di sebalik terowong SSH, pendedahkan hanya hujung witness yang dipetakan pada nama hos HTTPS berasingan dengan contoh Caddy ini. Ruang kerja lalai kemudian menggunakan https://witness.example.org, manakala ruang kerja lain menggunakan
https://witness.example.org/profiles/ID. Token masih diperlukan; panel dan laluan API lain tidak diteruskan oleh hos maya tersebut.
Pilih all untuk checkpoint yang diterbitkan secara berkala. Jeda lima minit bermaksud kira-kira 288
pos setiap ruang kerja setiap hari. changes/problems sengaja tidak menerbitkan beberapa pemeriksaan.
MTProxy adalah untuk klien Telegram pengumpul. Pemantauan HTTP dan Bot API HTTPS Telegram menggunakan laluan langsung/HTTP/SOCKS5 mereka sendiri (Bot API).
Di sebelah pengumpul, dengan Docker (hos yang sama — proses dan kunci yang berasingan, tetapi pengendali yang sama): masukkan nilai dalam .env dan mulakan profil.
TGWITNESS_WITNESS_TOKEN=tgww_...
TGWITNESS_WITNESS_BOT_TOKEN=123456:ABC...
TGWITNESS_WITNESS_CHANNEL=@your_witness_channel
# another workspace: TGWITNESS_WITNESS_COLLECTOR=http://tgwitness:8787/profiles/<workspace ID>
docker compose --profile witness up -d
docker compose logs witness # prints the witness key fingerprint
Untuk imej yang diterbitkan, gunakan docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d.
Pada pelayan orang lain (pemilikan berasingan): salin repositori ke sana, tetapkan
TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org serta tiga nilai di atas
dalam .env, kemudian
docker compose --project-directory . -f deploy/compose/compose.witness.yaml up -d
atau tanpa Docker:
python -m tgwitness.witness run --collector https://your-collector.example.org \
--token-file witness-token.txt --bot-token-file bot-token.txt --channel @your_witness_channel
Terbitkan ke Discord#
Saksi boleh menyiarkan ke saluran Discord sebagai ganti Telegram. Di Discord, buka
Sunting Saluran → Integrasi → Webhook, buat webhook dan salin URLnya. Dalam panel, pilih webhook Discord · saluran anda pada langkah 2. Pada hos saksi, simpan URL sebagai discord-webhook.txt di sebelah witness.json; ia tidak pernah sampai ke
pengumpul.
python -m tgwitness.witness run --collector https://your-collector.example.org \
--token-file witness-token.txt --discord-webhook-file discord-webhook.txt
Saksi mempunyai satu penerbit: saluran Telegram atau webhook Discord, bukan kedua-duanya. Pos
membawa pernyataan berasingan yang sama dan tidak boleh meming sesiapa. Pos yang lebih panjang daripada
2,000
aksara Discord akan digantikan dengan satu baris pendek dengan semakan penuh dilampirkan sebagai
witness-check.txt
. Setiap ID pos direkodkan sebagai witness.posted
. verify.py --channel
hanya membaca saluran Telegram, jadi untuk Discord simpan jurnal saksi: ia mengandungi setiap
semakan. Pos Discord tidak memberikan pengesah sebarang masa luaran.
Pilihan#
| Pilihan | Persekitaran | Lalai | Maksud |
|---|---|---|---|
--interval |
TGWITNESS_WITNESS_INTERVAL |
10 | Minit antara pemeriksaan, 1–1440 |
--timeout |
_TIMEOUT |
30 | Masa menunggu untuk pengumpul dan Bot API, 5–600 |
--post |
_POST |
all |
all: setiap pemeriksaan; changes: ketua baru atau masalah; problems: hanya masalah dan jawapan yang hilang |
--title |
_TITLE |
TgWitness witness |
Kata pertama setiap kiriman saluran |
--collector-fingerprint |
_COLLECTOR_FINGERPRINT |
– | Pasang kunci pengumpul dan bukannya mempercayai jawapan pertama |
--proxy |
_PROXY |
langsung | socks5://host:port atau http://host:port |
--bot-api |
_BOT_API |
https://api.telegram.org |
Alamat Bot API, contohnya pelayan Bot API tempatan |
--data-dir |
_DATA |
witness-data |
Kunci saksi dan jurnal |
--config |
_CONFIG |
– | Fail JSON dengan mana-mana pilihan di atas |
Alamat pengumpul, token dan saluran datang daripada --collector, --token atau
--token-file, --bot-token atau --bot-token-file, --discord-webhook-file dan --channel,
atau _COLLECTOR, _TOKEN, _TOKEN_FILE, _BOT_TOKEN, _BOT_TOKEN_FILE,
_DISCORD_WEBHOOK_FILE dan _CHANNEL, yang menyembunyikan rahsia daripada senarai proses.
Fail konfigurasi menggunakan nama pilihan dengan tanda hubung bawah, serta texts, yang menggantikan perkataan-perkataan dalam pos saluran:
{"collector": "https://your-collector.example.org", "token_file": "witness-token.txt",
"bot_token_file": "bot-token.txt", "channel": "@your_witness_channel",
"interval": 5, "timeout": 30, "post": "changes", "title": "Partner witness",
"texts": {"ok": "journal head", "no_response": "no answer from the collector", "records": "records"}}
Kunci texts: ok, key_changed, rollback, fork, invalid, no_response, collector,
records, head. Baris arahan diutamakan berbanding persekitaran, manakala persekitaran diutamakan berbanding fail. Pilihan atau kunci teks yang tidak dikenali akan menghentikan saksi dengan mesej dan bukannya diabaikan.
Penulisan tidak pernah menjejaskan pengesahan: verify.py memeriksa token yang disahkan di akhir setiap
pos. Dengan --post changes atau problems, pemeriksaan yang tidak diposkan masih terdapat dalam
jurnal saksi dan verify.py menyenaraikannya sebagai tidak pernah diposkan; rekod permulaan menamakan
dasar. Setiap pemeriksaan masih muncul dalam jurnal, jadi lebih sedikit pos bermakna lebih sedikit kali bertarikh
oleh Telegram, bukan lebih sedikit pemeriksaan.
Tanpa saluran, saksi masih menyimpan jurnalnya. Simpan cap jari kunci saksi (python -m tgwitness.witness fingerprint) di tempat lain.
Halaman bukti awam untuk beberapa ruang kerja#
python -m tgwitness.proof menyaksikan sehingga 32 ruang kerja sekaligus dan menyediakan halaman baca sahaja dengan semakan berasingan terkini bagi setiap satu. Setiap ruang kerja mendapat kunci saksi dan jurnal sendiri di bawah folder data serta kunci pengumpul yang dipin; penghantaran ke saluran Telegram adalah pilihan bagi setiap ruang kerja. Mulakan dari proof.config.example:
| Medan | Maksud |
|---|---|
title |
Tajuk halaman, 1–100 aksara |
data_dir |
Kunci dan jurnal saksi, berbanding fail; lalai proof-data |
interval, timeout |
Minit antara pemeriksaan (1–1440, lalai 5); saat untuk menunggu (5–600, lalai 20) |
workspaces[].id, label |
Alias huruf kecil dan nama yang dipaparkan |
workspaces[].collector |
Alamat pengumpul; ruang kerja lain berakhir dengan /profiles/<workspace ID> |
workspaces[].collector_fingerprint |
Diperlukan, berbeza untuk setiap ruang kerja |
workspaces[].token_file |
Fail dengan token saksi baca sahaja bagi ruang kerja tersebut |
workspaces[].channel, bot_token_file |
Pilihan, secara bersama: hantar setiap semakan ke saluran |
workspaces[].proxy, bot_api |
Alamat API laluan dan Bot pilihan |
python -m tgwitness.proof --config proof.json --check-config
python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790
Perintah pertama mengesahkan fail dan fail token tanpa membuka sambungan. Halaman ini hanya menjawab GET dan HEAD:
/menunjukkan setiap ruang kerja; ruang kerja yang tidak diperiksa untuk selang 2.5 ditandakan sebagai lapuk./api/proofmengembalikan nilai yang sama seperti JSON./api/proof/<id>memuat turun kenyataan bertandatangan terkini (tgwitness-public-proof-v1): nombor rekod saksi dan hash, status, kunci pengumpul yang dipin, checkpoint, koleksi pengira dan sama ada pos saluran berjaya, ditandatangani oleh kunci saksi ruang kerja tersebut./healthzmenjawab 503 apabila monitor ruang kerja telah berhenti.
Berikan halaman nama hosnya sendiri, seperti dalam
Caddyfile.proof.example. Untuk pengesahan, eksport jurnal saksi ruang kerja dengan
python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip dan gunakan ia seperti yang diterangkan di bawah.
Sahkan#
Pada pihak saksi, eksport jurnalnya:
python -m tgwitness.witness export --out witness.zip
# Docker (add -f deploy/compose/compose.witness.yaml on a witness server):
docker compose exec witness python -m tgwitness.witness export --out /witness/witness.zip
docker compose cp witness:/witness/witness.zip .
Kemudian, di mana-mana, dengan ZIP yang ditandatangani oleh pengumpul dan alamat saluran awam:
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
--witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel https://t.me/s/your_witness_channel
--channel juga menerima eksport Telegram Desktop (Eksport sejarah sembang → JSON menghasilkan
result.json) atau salinan halaman yang disimpan; ini memeriksa kandungan pos tetapi tidak memberikan sebarang
masa luaran.
verify.py memeriksa jurnal saksi (rantaian dan tandatangan), kemudian memeriksa sama ada setiap 'head' yang dilihat saksi adalah sebahagian daripada jurnal yang dieksport: rekod pada kiraan tersebut mesti mempunyai hash yang tepat itu. Sebarang head yang tidak sepadan akan gagal pengesahan — jurnal telah diubah selepas saksi melihatnya. Ia juga melaporkan head yang dilihat selepas eksport, anomali yang direkodkan oleh saksi, jawapan yang gagal, tempoh di mana checkpoint sepadan wujud dalam eksport ini ("Disaksikan dari X ke Y") dan kekosongan. Checkpoint kemudian tidak melanjutkan tempoh-tempoh tersebut. Keputusan termasuk nombor rekod sepadan terakhir dan bilangan rekod di hujung yang tiada checkpoint sepadan. Hanya jawapan yang disahkan oleh kunci eksport itu sendiri yang dikira: eksport yang disahkan oleh kunci yang tidak pernah dilihat oleh saksi dilaporkan sebagai tidak disaksikan, dan tanpa --fingerprint penandatangananya kekal tidak dipin. Dengan --channel setiap kiriman yang disahkan mesti sepadan dengan jurnal saksi, rekod demi rekod: kiriman yang diubah gagal pengesahan, kiriman yang hilang disenaraikan. Kespadanan token mengesahkan kandungan; tarikh berada di luar token yang disahkan.
Dengan alamat https://t.me/s/… atau https://telegram.me/s/… yang aktif, pengesah membaca tarikh setiap kiriman daripada halaman tersebut pada masa pengesahan. Telegram menetapkan tarikh tersebut; tarikh pos yang disunting tidak digunakan. Tarikh terawal bagi pos sedemikian di kepala eksport adalah masa luaran untuk rekod terakhir, yang memenuhi syarat minimum bagi bukti. Tarikh daripada mana-mana sumber lain, seperti result.json yang dibekalkan, halaman yang disimpan atau alamat web lain, adalah metadata yang dibekalkan, bukan masa bebas; hasil menunjukkan tempat tarikh posnya berasal (post_date_verification).
Perlukan sempadan eksport yang disaksikan#
Untuk penyerahan yang mesti merangkumi rekod akhir disaksikan, tambahkan --require-witness:
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
--witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness
Ini memerlukan cap jari saksi yang disimpan secara berasingan, satu kunci selain kunci pengumpul, dan satu titik pemeriksaan yang sepadan di penghujung tepat eksport ini. Satu titik pemeriksaan yang merangkumi hanya pratonton awal adalah tidak mencukupi. Jeda pengumpulan, biarkan saksi memerhati keadaan akhir, dan eksport sebelum penulisan jurnal selanjutnya; jika jurnal berubah, simpan satu lagi titik pemeriksaan dan eksport keadaan itu. Satu titik pemeriksaan kemudian sahaja tidak dapat mengesahkan hash akhir eksport yang lebih pendek.
Apabila --channel juga disertakan, pos yang didakwa hilang atau set padanan kosong akan menyebabkan pemeriksaan ketat ini gagal. Tanpa penanda aras ini, pemeriksaan integriti biasa masih melaporkan rekod yang tidak disaksikan tanpa menolak arkib yang sebaliknya utuh.
Simpan jurnal saksi dan kunci terpasangnya secara berasingan. Semakan dalam talian mengesahkan kesinambungan antara titik pemeriksaan; pengesahan luar talian membandingkan setiap titik pemeriksaan yang disimpan dengan eksport. Kepala warisan tanpa bukti kesinambungan mengekalkan perbandingan luar talian dan dilaporkan tanpa pengesahan kesinambungan dalam talian. Laporan menyenaraikan masa henti saksi dan penerbitan yang gagal mengikut selang masa.
Segel harian dan kalendar cap masa yang tidak tersedia#
Saksi menutup sempadan jurnal hari UTC sebelumnya dan menghantar hash meterai yang ditandatangani itu ke OpenTimestamps. Penyerahan kalendar menunggu bukti; hanya komitmen Bitcoin yang diperiksa secara bebas menerima pengesahan dalam pengesah.
Jika semua kalendar gagal, meterai yang ditandatangani dan percubaan yang tidak berjaya kekal dalam jurnal. Pas penyelenggaraan setiap jam akan mencuba semula rekod asal itu, termasuk selepas but semula atau pertukaran tarikh. Ia mengimbas paling banyak 32 meterai, menghantar paling banyak dua penghantaran yang hilang dan mengambil masa paling banyak 60 saat untuk percubaan semula setiap pusingan. Penunjuk arah berterusan akan berputar melalui meterai yang lebih lama. Penghantaran yang disimpan mengikuti laluan peningkatan bukti sedia ada.
Percubaan semula tidak menulis semula meterai, mengubah tarikh asalnya atau mendakwa bahawa kalendar menerimanya lebih awal. Komitmen Bitcoin yang kemudian kekal sebagai pengesahan luaran yang kemudian. Bukti yang hilang kekal none; bukti yang menunggu kekal pending sehingga pengesah memeriksanya secara bebas.