From dee040e35b3d8c830e3a11c20dedf6d492d25d1a Mon Sep 17 00:00:00 2001
From: Liu Xiang Qian <smartlitchi@gmail.com>
Date: Sun, 2 Nov 2025 11:44:57 +0800
Subject: [PATCH] docs: Enhance timestamp/timezone troubleshooting based on
 Issue #60 Enhanced the Exchange API errors section with more detailed
 solutions for timestamp-related failures, based on Issue #60. Problem: -
 code=-1021: Timestamp outside of recvWindow - System time not synced with
 Binance servers - Docker container time drift Enhanced Solutions: 1. System
 Time Sync (Multiple methods)    - ntpdate pool.ntp.org (recommended)    -
 ntpdate with different NTP servers    - timedatectl for automatic sync    -
 Aliyun NTP for China users 2. Docker-specific fixes    - Check container time
 vs host time    - Restart Docker service    - Add TZ environment variable 3.
 API Key verification steps    - Regeneration procedure    - Permission
 checklist 4. Rate limit considerations    - Reduce trader count    - Increase
 decision interval Both English and Chinese versions updated. Fixes: #60
 Co-Authored-By: tinkle-community <tinklefund@gmail.com>

---
 docs/guides/TROUBLESHOOTING.md       | 72 +++++++++++++++++++++++-----
 docs/guides/TROUBLESHOOTING.zh-CN.md | 72 +++++++++++++++++++++++-----
 2 files changed, 120 insertions(+), 24 deletions(-)

diff --git a/docs/guides/TROUBLESHOOTING.md b/docs/guides/TROUBLESHOOTING.md
index e957a5bc..e2ccf179 100644
--- a/docs/guides/TROUBLESHOOTING.md
+++ b/docs/guides/TROUBLESHOOTING.md
@@ -275,24 +275,72 @@ NOFX_BACKEND_PORT=8081
 
 #### ❌ Exchange API Errors
 
-**Error:** `invalid signature` / `timestamp` errors
+**Common Errors:**
+- `code=-1021, msg=Timestamp for this request is outside of the recvWindow`
+- `invalid signature`
+- `timestamp` errors
 
-**Solutions:**
-1. **Check System Time:**
-   ```bash
-   date  # Should be accurate
-   # If wrong, sync with NTP:
-   sudo ntpdate -s time.nist.gov
-   ```
+**Root Cause:**
+System time is inaccurate, differing from Binance server time by more than allowed range (typically 5 seconds).
 
-2. **Verify API Keys:**
+**Solution 1: Sync System Time (Recommended)**
+
+```bash
+# Method 1: Use ntpdate (most common)
+sudo ntpdate pool.ntp.org
+
+# Method 2: Use other NTP servers
+sudo ntpdate -s time.nist.gov
+sudo ntpdate -s ntp.aliyun.com  # Aliyun NTP (fast in China)
+
+# Method 3: Enable automatic time sync (Linux)
+sudo timedatectl set-ntp true
+
+# Verify time is correct
+date
+# Should show current accurate time
+```
+
+**Docker Environment Special Note:**
+
+If using Docker, container time may be out of sync with host:
+
+```bash
+# Check container time
+docker exec nofx-backend date
+
+# If time is wrong, restart Docker service
+sudo systemctl restart docker
+
+# Or add timezone in docker-compose.yml
+environment:
+  - TZ=Asia/Shanghai  # or your timezone
+```
+
+**Solution 2: Verify API Keys**
+
+If errors persist after time sync:
+
+1. **Check API Keys:**
    - Not expired
    - Have correct permissions (Futures enabled)
    - IP whitelist includes your server IP
 
-3. **Rate Limits:**
-   - Binance has strict rate limits
-   - Reduce number of traders or decision frequency
+2. **Regenerate API Keys:**
+   - Login to Binance → API Management
+   - Delete old key
+   - Create new key
+   - Update NOFX configuration
+
+**Solution 3: Check Rate Limits**
+
+Binance has strict API rate limits:
+
+- **Requests per minute limit**
+- Reduce number of traders
+- Increase decision interval (e.g., from 1min to 3-5min)
+
+**Related Issue:** [#60](https://github.com/tinkle-community/nofx/issues/60)
 
 ---
 
diff --git a/docs/guides/TROUBLESHOOTING.zh-CN.md b/docs/guides/TROUBLESHOOTING.zh-CN.md
index 5274664b..b070c8a0 100644
--- a/docs/guides/TROUBLESHOOTING.zh-CN.md
+++ b/docs/guides/TROUBLESHOOTING.zh-CN.md
@@ -275,24 +275,72 @@ NOFX_BACKEND_PORT=8081
 
 #### ❌ 交易所 API 错误
 
-**错误:** `invalid signature` / `timestamp` 错误
+**常见错误:**
+- `code=-1021, msg=Timestamp for this request is outside of the recvWindow`
+- `invalid signature`
+- `timestamp` 错误
 
-**解决方案:**
-1. **检查系统时间:**
-   ```bash
-   date  # 应该准确
-   # 如果错误，与 NTP 同步:
-   sudo ntpdate -s time.nist.gov
-   ```
+**根本原因:**
+系统时间不准确，与币安服务器时间相差超过允许范围（通常是 5 秒）。
 
-2. **验证 API 密钥:**
+**解决方案 1: 同步系统时间（推荐）**
+
+```bash
+# 方法 1: 使用 ntpdate (最常用)
+sudo ntpdate pool.ntp.org
+
+# 方法 2: 使用其他 NTP 服务器
+sudo ntpdate -s time.nist.gov
+sudo ntpdate -s ntp.aliyun.com  # 阿里云 NTP (中国大陆快)
+
+# 方法 3: 启用自动时间同步 (Linux)
+sudo timedatectl set-ntp true
+
+# 验证时间是否正确
+date
+# 应该显示正确的当前时间
+```
+
+**Docker 环境特别注意:**
+
+如果使用 Docker，容器时间可能与宿主机不同步：
+
+```bash
+# 检查容器时间
+docker exec nofx-backend date
+
+# 如果时间错误，重启 Docker 服务
+sudo systemctl restart docker
+
+# 或在 docker-compose.yml 中添加时区设置
+environment:
+  - TZ=Asia/Shanghai  # 或您的时区
+```
+
+**解决方案 2: 验证 API 密钥**
+
+如果时间同步后仍有错误：
+
+1. **检查 API 密钥:**
    - 未过期
    - 有正确权限（已启用合约）
    - IP 白名单包含您的服务器 IP
 
-3. **速率限制:**
-   - 币安有严格的速率限制
-   - 减少交易员数量或决策频率
+2. **重新生成 API 密钥:**
+   - 登录币安 → API 管理
+   - 删除旧密钥
+   - 创建新密钥
+   - 更新 NOFX 配置
+
+**解决方案 3: 检查速率限制**
+
+币安有严格的 API 速率限制：
+
+- **每分钟请求数限制**
+- 减少交易员数量
+- 增加决策间隔时间（例如从 1 分钟改为 3-5 分钟）
+
+**相关 Issue:** [#60](https://github.com/tinkle-community/nofx/issues/60)
 
 ---