Vận hành máy chủ

Quản trị và cấu hình

Trang quản trị, gửi mã đăng ký (SMS, email), các giá trị cấu hình máy chủ, sao lưu và bảo mật — tài liệu tham chiếu cho người vận hành.

Máy chủ có sẵn một trang quản trị mở bằng trình duyệt. Tại đây bạn xem trạng thái máy chủ, quyết định cách gửi mã đăng ký và đăng nhập, và quản lý người dùng cũng như bot. Tài liệu này là tài liệu tham chiếu, tập hợp trang quản trị và các giá trị cấu hình máy chủ vào một chỗ. Nếu bạn cần cài đặt trước, hãy xem Cài đặt máy chủ.

Giao diện trang quản trị hiện bằng tiếng Hàn. Khi tài liệu này nhắc đến một tab, nút hay mục cài đặt, nhãn tiếng Hàn đúng như trên màn hình được ghi kèm trong ngoặc.

Mở trang quản trị

Trang quản trị nằm ở /admin/ trên cổng HTTP quản trị (8080 trong cấu hình vận hành), và chỉ mở trên chính máy chủ (127.0.0.1). Người vận hành truy cập qua tunnel SSH.

# Trên máy tính của bạn (để lệnh này tiếp tục chạy)
ssh -N -L 8080:127.0.0.1:8080 <người-dùng>@<máy-chủ>
# Trình duyệt: http://localhost:8080/admin/

# Token (trên máy chủ)
sudo cat /srv/pabal/pabal_server/data/admin-token

Nhập token rồi bấm Mở (열기). Trình duyệt sẽ ghi nhớ token; muốn xóa thì bấm Xóa token (토큰 지우기) ở góc trên bên phải. Muốn tự đặt token, hãy truyền TELEGRAM_ADMIN_TOKEN (từ 16 ký tự trở lên) — khi đó máy chủ sẽ không ghi tệp token.

Các tab hiển thị gì

Các thao tác nguy hiểm (đăng xuất, chặn, hủy mã) phải bấm hai lần mới được thực hiện.

Mã đăng ký và đăng nhập

Khi người dùng nhập số điện thoại vào ứng dụng, máy chủ tạo mã và gửi theo cách đã chọn trong tab Cài đặt (설정).

• Với cách email, đăng ký mới có thể dùng địa chỉ bất kỳ, và địa chỉ đó trở thành email đăng nhập của tài khoản. Tài khoản đã có chỉ nhận mã qua email đăng nhập đã đăng ký — để ngăn việc ai đó điền địa chỉ của mình vào số điện thoại của người khác để vào tài khoản. Tài khoản đã có mà chưa có email đăng nhập sẽ được gửi mã qua SMS (nếu đã cấu hình) hoặc qua trang quản trị. Bạn có thể nhập email đăng nhập cho người dùng trong tab Người dùng (사용자).
• Việc gửi diễn ra ở phía sau, nên ứng dụng chuyển ngay sang màn hình nhập mã. Kết quả gửi (thành công, thất bại và lý do) hiện trong tab Mã đăng ký.
• Chỉ đăng ký (nhập tên) được sau khi đã nhập đúng mã. Mã sai chỉ được chấp nhận trong số lần cho phép; sau đó ngay cả mã đúng cũng bị từ chối.
• Đổi số của tài khoản (Cài đặt → số điện thoại trong ứng dụng) mặc định bị đóng, ứng dụng sẽ báo lỗi. Khi bật Cho phép đổi số, mã chỉ được gửi tới số mới qua SMS, bất kể cách gửi nào (tab Mã đăng ký không hiển thị mã này, kể cả khi bật hiển thị mã — người nhận mã ở đó chưa chắc là chủ của số), với nội dung riêng, là nội dung đổi số trong cài đặt SMS (번호 바꾸기 문구; mặc định [파발] 번호 바꾸기 확인 코드: {code}). Khoảng chờ gửi lại và giới hạn mỗi ngày áp dụng cho cả số mới lẫn tài khoản; số bị chặn hoặc bị tạm khóa, và số mà tài khoản khác đang dùng, bị từ chối cả khi xin mã lẫn khi chuyển. Mã chỉ đúng cho tài khoản đó và số đó, và chỉ dùng được một lần; mã đăng nhập của người khác đang chờ số đó vẫn giữ nguyên. Sau khi chuyển, số cũ không còn đăng nhập được vào tài khoản đó.

Cài đặt — đăng ký và đăng nhập

Cài đặt — SMS

Nội dung tin nhắn có thể chứa {code} (mã) và {minutes} (thời hạn hiệu lực). Mặc định: [파발] 인증 코드: {code} (nghĩa là "[Pabal] Mã xác thực: {code}"; mặc định này bằng tiếng Hàn, bạn có thể đổi nội dung). Sau khi lưu, hãy kiểm tra bằng Gửi thử (테스트 발송).

Cài đặt — email (SMTP)

Địa chỉ gửi phải là địa chỉ mà tài khoản SMTP được phép gửi. Tiêu đề và nội dung cũng dùng được {code}, {minutes}.

Quản lý người dùng

• Đăng xuất mọi thiết bị (모든 기기 로그아웃): ngắt mọi phiên đăng nhập (khóa xác thực) của tài khoản đó. Dùng cho người dùng bị mất thiết bị.
• Chặn số (번호 차단): số đó không nhận được mã, và tài khoản của số đó bị đăng xuất ngay khỏi mọi thiết bị. Giống với danh sách chặn số điện thoại (전화번호 차단) trong tab Cài đặt.
• Email đăng nhập (로그인 이메일): cần thiết để tài khoản đã có đăng nhập bằng email khi dùng cách email.
• Xóa tài khoản (계정 삭제): dùng cho người dùng đã yêu cầu xóa tài khoản, sau khi xác nhận đúng là họ. Xóa đúng những gì chức năng xóa tài khoản trong ứng dụng xóa, và không thể hoàn tác. Chỉ thực hiện sau khi nhập lại ID hoặc số điện thoại của tài khoản và để lại ghi chú về việc yêu cầu đến từ đâu và đã xác nhận danh tính thế nào. Ghi chú được giữ cùng ID và ngày (số điện thoại, địa chỉ email, cùng tên và tên người dùng của tài khoản bị loại khỏi ghi chú). Với yêu cầu qua email không gửi từ email đăng nhập của tài khoản, cùng cửa sổ đó gửi mã qua SMS đến số của tài khoản; hãy nhập mã mà người đó gửi lại qua email. Không thể xóa bot và các tài khoản của chính máy chủ ở đây.
• @BotFather là bot bên trong máy chủ nên không thể bị đăng xuất.

Quản lý bot

Trong tab Bot (봇), bạn xem cách kết nối của từng bot — có đang kết nối qua MTProto không, có gọi getUpdates qua HTTP trong 1 phút gần đây không, địa chỉ webhook là gì và hiện có đang thất bại không (kèm lý do). Nếu số update đang chờ cứ tăng mãi, nghĩa là chương trình bot đã dừng hoặc webhook đang thất bại. Việc xóa bot và cấp lại token do người tạo bot thực hiện tại @BotFather.

Tab Thoại

Đây là nơi vận hành bot thoại (bot mà khi có người gọi thì một mô hình giọng nói AI trả lời — xem Bot thoại). Tab vẫn hiện kể cả khi máy chủ chưa bật tính năng thoại, và mục trạng thái cho biết còn thiếu gì. Cách bật xem ở Cài đặt máy chủ — Bot thoại. Tab làm mới mỗi 5 giây.

Cho phép là một lần xem xét. Ở chế độ "chỉ bot đã cho phép", cho phép một bot nghĩa là cho phép chỉ dẫn, lời chào và công cụ hiện tại của nó (ở chế độ âm thanh gốc thì là địa chỉ âm thanh gốc). Nếu chủ bot thay đổi bất kỳ thứ nào trong số đó, bảng bot hiện dòng "chỉ dẫn · lời chào đã thay đổi — phải xem lại và cho phép lại thì mới nhận cuộc gọi" (지시문·인사말이 바뀜 — 확인하고 다시 허용해야 전화를 받습니다), và bot đó không nhận cuộc gọi cho đến khi bạn bấm Xem lại và cho phép lại (확인하고 다시 허용). Với bot có ngôn ngữ không phải tiếng Hàn hay tiếng Anh, điều này cũng áp dụng ở chế độ "mọi bot tạo bằng @BotFather" — vì bước kiểm tra quy tắc tự động khi lưu chỉ đọc được tiếng Hàn và tiếng Anh. Bảng của những bot đó hiện dòng "bot không dùng tiếng Hàn hay tiếng Anh (kiểm tra quy tắc tự động không đọc được): hãy đọc chỉ dẫn và lời chào — phải xem lại và cho phép lại thì mới nhận cuộc gọi" (한국어·영어가 아닌 봇 (자동 규칙 검사가 읽지 못함): 지시문·인사말을 읽어 주세요 — 확인하고 다시 허용해야 전화를 받습니다), nên hãy nhờ người đọc được ngôn ngữ đó đọc chỉ dẫn và lời chào rồi cho phép.

• Một ngày được tính theo múi giờ của máy chủ (TELEGRAM_VOICE_TIME_ZONE, mặc định Asia/Seoul). Khi nhận một cuộc gọi, máy chủ định độ dài tối đa trong phạm vi thời gian còn lại của ngày đó và giữ trước khoảng ấy ở mọi giới hạn; khi kết thúc, chỉ số giây thực tế theo đồng hồ máy chủ bị tính. Cuộc gọi nhận bằng khóa riêng của chủ bot chỉ dùng giới hạn của người gọi.
• Chủ bot chỉ có thể đặt độ dài một cuộc gọi (mặc định 300 giây) và số cuộc gọi đồng thời của bot mình trong phạm vi các giới hạn này.
• Mọi thao tác (công tắc dừng khẩn cấp, công khai, cho phép, tạm dừng, ngắt cuộc gọi, giới hạn …) được ghi vào nhật ký hoạt động của tab Mã đăng ký (가입 코드) với tiền tố 음성: … (nghĩa là "thoại: …").
• Các chỉ số chất lượng của cuộc gọi thoại (thời gian đến âm thanh đầu tiên, thời gian đến khi dừng lại lúc bị ngắt lời, thời gian trả lời của công cụ …) không có trong tab này mà chỉ có ở /metrics của cổng quản trị (các tên bắt đầu bằng voice. trong JSON, và bằng voice_ trong định dạng Prometheus /metrics?format=prometheus). Không có thông tin về người, bot hay lời nói, chỉ có tổng số.

Bạn cũng làm được những việc này qua API quản trị (tất cả đều cần Authorization: Bearer <token>): GET /admin/api/voice, GET /admin/api/voice/bots/<id>, dùng POST cho voice/kill {"on": true}, voice/launch {"launched": true, "confirm": "…"}, voice/transcripts {"allowed": true, "confirm": "…"}, voice/testers·voice/testers/remove {"userId": …}, voice/gate {"botGate": "ALLOWLIST"}, voice/bots/allow·voice/bots/disallow {"botId": …}, voice/bots/<id>/suspend {"reason": "…"}·…/lift·…/name-exempt, voice/calls/<id>/end; còn giới hạn thì dùng /admin/api/settings/voice. Cuộc gọi từ bot: voice/outbound {"on": true, "confirm": "…"}, voice/outbound/settings {"countries": […], "limits": {…}}, GET /admin/api/voice/outbound/bots/<id>, voice/outbound/bots/allow {"botId": …, "expect": "<outboundReviewHash>"}·voice/outbound/bots/disallow, voice/outbound/bots/<id>/lift.

Biến môi trường

Máy chủ đọc tệp cấu hình (server-config.json) rồi ghi đè bằng biến môi trường. Tệp compose vận hành đã đặt sẵn các giá trị dưới đây, nên thông thường bạn chỉ cần sửa .env.

Biến môi trường — bot thoại

Khi vận hành, tệp bổ sung deploy/docker-compose.voice.yml đặt một phần trong số này từ giá trị trong .env — liên kết, chuyển tiếp, múi giờ, giới hạn, người thử nghiệm và bản build tối thiểu; phần còn lại được thêm theo từng tính năng sau khi rà soát riêng (Cài đặt máy chủ — Bot thoại). Các cài đặt VOICE_* của gateway (pabal-voice) nằm trong voice/README.md của kho mã.

Tệp dữ liệu

Ghi chú bảo mật

• Đừng mở cổng quản trị trực tiếp ra Internet. Caddy trong cấu hình vận hành chặn các đường dẫn quản trị như /admin, /health, /metrics bằng 404.
• Mọi yêu cầu dữ liệu quản trị đều cần Authorization: Bearer <token>, và trang của website khác không thể đọc được dữ liệu này.
• Các giá trị bí mật SMS và SMTP chỉ nằm trong operations.json; màn hình và API chỉ báo "đã lưu". Nếu để trống ô giá trị bí mật khi lưu, giá trị cũ vẫn được giữ.
• Token và giá trị bí mật không bị ghi vào log, còn số điện thoại trong log được che bớt. Địa chỉ Bot API (có chứa token) cũng không được ghi vào log.
• Token thiết bị của thông báo đẩy chỉ được ghi vào log dưới dạng dấu vân tay, còn nội dung tệp khóa Firebase và nội dung thông báo không được ghi vào log.
• Khóa xác thực nằm trong DB, nên người truy cập được DB có thể giải mã lưu lượng của người dùng. Hãy bảo vệ DB và bản sao lưu kỹ như khóa RSA.

Giới hạn

• Mã đang chờ và lịch sử gần đây nằm trong bộ nhớ nên sẽ mất khi máy chủ khởi động lại (chỉ cần yêu cầu lại trong ứng dụng).
• Việc gửi thật của nhà cung cấp SMS cần được kiểm tra bằng tài khoản của từng nhà cung cấp. Máy chủ tạo yêu cầu theo đúng tài liệu của từng nhà cung cấp.
• Chưa có: buộc xóa bot, xem tin nhắn, xem log, biểu đồ, thống kê thông báo đẩy (thông báo đẩy được kiểm tra qua log máy chủ).