Skip to content

About

面向监考和教室大屏的 NTP 同步网页时钟,提供授时 API、全屏显示、倒计时/正计时和部署文档。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

NTP Web Clock

NTP Web Clock is a browser-facing exam clock and timer. The browser does not talk to NTP directly. A small Node.js backend queries configured NTP servers over UDP, exposes calibrated time through HTTP APIs, and the frontend uses that data to keep the displayed time close to the trusted time source.

It is designed for classroom screens, exam invigilation, meeting rooms, and internal web pages that need a readable clock with better stability than a browser-only timer.

Features

  • Large responsive clock for desktop, projector, and mobile views.
  • Fullscreen mode that hides controls and keeps only the clock body.
  • Time API backed by one or more configurable NTP sources.
  • Multi-sample frontend sync with RTT filtering and offset smoothing.
  • Monotonic clock progression and safe timer recovery after page reloads.
  • Cross-source NTP consistency checks before selecting a low-delay source.
  • Enhanced /api/time/sync endpoint for callers that want server-side multi-sample NTP filtering.
  • Countdown and count-up timer modes.
  • Timer controls for start, stop/end, pause, and reset.
  • Diagnostics for NTP source, NTP delay, web round-trip time, last update, and server time offset.
  • No external npm dependencies.

Quick Start

cd ntp-web-clock
npm test
npm start

Default runtime values:

HOST=0.0.0.0
PORT=8080
TIMEZONE=Asia/Shanghai
NTP_SERVERS=time.cloudflare.com,time.google.com,pool.ntp.org

For an internal deployment, override NTP_SERVERS with your own NTP hosts:

HOST=0.0.0.0 \
PORT=8080 \
TZ=Asia/Shanghai \
TIMEZONE=Asia/Shanghai \
NTP_SERVERS=<NTP_SERVER_1>,<NTP_SERVER_2>,<NTP_SERVER_3> \
npm start

Then open:

http://<SERVER_IP>:8080/

API

GET /api/time

Returns one calibrated time result.

Useful fields:

  • epochMs: calibrated Unix timestamp in milliseconds.
  • iso: ISO timestamp.
  • source: ntp, ntp-stale, or system.
  • server: selected NTP source for this sample.
  • delayMs: server-to-NTP UDP round-trip delay.
  • offsetMs: server system clock offset against NTP.
  • serverProcessingMs: HTTP request processing time on the server.

Request a backend NTP refresh (subject to the shared minimum sampling interval):

/api/time?refresh=1

Ordinary, forced, and text requests share a 1500 ms minimum NTP attempt interval (NTP_MIN_INTERVAL_MS), including failed attempts. During cooldown they reuse a valid calibration or return the documented stale/system fallback. HTTP responses themselves are not delayed by this cooldown.

GET /api/time/sync

Runs multiple NTP samples on the server, filters high-delay and outlier samples, and returns a more stable result.

/api/time/sync?samples=7

samples can be 1-9.

Concurrent requests share the active burst, which collects distinct samples. A fresh ordinary sample can count as its first sample. Bursts have a separate 10000 ms cooldown (API_SYNC_MIN_INTERVAL_MS); requests during that interval reuse the last usable burst, so the returned syncStats.totalSamples may differ from the requested count. Ordinary refreshes join a running burst.

The consensus field reports responding and agreeing source counts. With multiple usable sources, a majority must agree before delay-based selection. Disagreement invokes stale/system fallback; a single responding source remains usable but cannot be cross-checked.

GET /api/time.txt

Returns one plain-text timestamp line for scripts and simple devices.

GET /api/health

Returns service health, configured NTP sources, the latest sync result, and the latest error.

Deployment

The repository includes a user-level systemd unit at:

deploy/ntp-web-clock.service

Before deployment, edit these values for your environment:

WorkingDirectory=%h/apps/ntp-web-clock
Environment=HOST=0.0.0.0
Environment=PORT=8080
Environment=TIMEZONE=Asia/Shanghai
Environment=NTP_SERVERS=<NTP_SERVER_1>,<NTP_SERVER_2>,<NTP_SERVER_3>
Environment=NTP_MIN_INTERVAL_MS=1500
Environment=API_SYNC_MIN_INTERVAL_MS=10000

See DEPLOYMENT.md and 部署文档.md for full deployment instructions.

Development

See DEVELOPMENT.md for architecture, time-sync logic, frontend behavior, and maintenance notes.

Version And Upload Log

See TIMESTAMP_LOG.md. It records GitHub upload events, commit IDs, repository location, and handoff notes for switching between machines or repositories.

About

面向监考和教室大屏的 NTP 同步网页时钟,提供授时 API、全屏显示、倒计时/正计时和部署文档。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages