From ef4b148c1af01e5e4c964aace62aa0a2d105ac7a Mon Sep 17 00:00:00 2001
From: Ubuntu <ubuntu@localhost.localdomain>
Date: Thu, 17 Sep 2026 10:56:06 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E8=A1=A5=E5=85=A8=E9=83=A8?=
 =?UTF-8?q?=E7=BD=B2=E6=96=B9=E5=BC=8F=E4=B8=8E=E7=8E=AF=E5=A2=83=E7=BA=A6?=
 =?UTF-8?q?=E5=AE=9A=EF=BC=88=E5=B7=A5=E4=BD=9C=E6=B5=81=E3=80=81=E5=87=AD?=
 =?UTF-8?q?=E6=8D=AE=E3=80=81CRLF=E3=80=81i18n=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9860057..6da6ad3 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,46 @@
 # qianshi
 
-千视科技官网
\ No newline at end of file
+千视科技官网 · https://qianshi.cool
+
+## 部署
+
+```bash
+python deploy.py "提交信息"
+```
+
+**工作流：本地 commit + push → 服务器 git pull**
+
+服务器只做 pull，不 commit。pull 只移动引用、不产生新 commit。
+
+> 历史上用「SFTP 上传 + 服务器 commit」曾导致同一改动被提交两次
+> （本地一次、服务器一次），author 与时间戳不同 → 同 tree 生出两个
+> commit ID → 分支 `ahead 1, behind 1` 反复交叉。现已固化为
+> `deploy.py`，不要再在服务器上手动 commit。
+
+## 环境
+
+| 项 | 值 |
+| --- | --- |
+| 线上 | https://qianshi.cool |
+| 服务器 | 106.55.169.92，站点目录 `/var/www/qianshi` |
+| Gitea | 与服务器同机，`http://127.0.0.1:3000/weizhiqiang/qianshi.git` |
+| 仓库 remote | 本地走 `106.55.169.92:3000`，服务器走 `127.0.0.1:3000`（loopback） |
+
+### 非交互凭据（已配置，勿删）
+
+```
+本地 与服务器:
+  git config --global credential.helper store
+  ~/.git-credentials   ← 含 Gitea HTTP 密码，权限 600
+  GIT_TERMINAL_PROMPT=0  ← 缺凭据立即失败，不会挂起等交互
+```
+
+## 约定
+
+- **CRLF**：已提交 `.gitattributes "* -text"` 禁用 git 行尾归一化。
+  改 HTML 用 `newline=''` 读写，否则 LF/CRLF 分叉产生无意义 diff。
+- **i18n**：新增文案须同时加入 `i18n.js` 的 `DICT`，英文值全局唯一
+  （反向字典 `REV` 由 `REV[DICT[k]]=k` 构建，英文重复会致 ZH→EN→ZH 错译）。
+- **批量维护脚本**（`gen_software_detail.py` / `update_site.py` /
+  `update_address.py` / `add_logo.py` / `fix_visual.py`）含本机绝对路径，
+  已在 `.gitignore` 中排除，不属于交付物。