更新内容

README.md

@@ -1,20 +1,130 @@
-<div align="center">
-<img width="1200" height="475" alt="GHBanner" src="https://ai.google.dev/static/site-assets/images/share-ais-513315318.png" />
-</div>
+# 言の葉写字板
 
-# Run and deploy your AI Studio app
+一个用于歌词/日语文本抄写、假名标注和注释管理的写字板。
 
-This contains everything you need to run your app locally.
+## 本地开发
 
-View your app in AI Studio: https://ai.studio/apps/d4d25382-dcc2-43cb-97a3-541137bcfafe
+```bash
+npm install
+npm run dev
+```
 
-## Run Locally
+本地开发地址默认是：
 
-**Prerequisites:**  Node.js
+```text
+http://localhost:3001/
+```
 
+开发模式下，`vite.config.ts` 会提供本地 `/api/saves`，文档保存在项目根目录的 `saves/`。
 
-1. Install dependencies:
-   `npm install`
-2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
-3. Run the app:
-   `npm run dev`
+## 生产运行
+
+生产环境使用独立 Express 服务：
+
+```bash
+npm install
+npm run build
+npm run start
+```
+
+默认监听：
+
+```text
+http://0.0.0.0:3002
+```
+
+可用环境变量：
+
+```bash
+PORT=3002
+HOST=0.0.0.0
+SAVES_DIR=/opt/kotonoha/data/saves
+```
+
+生产服务会：
+
+- 提供 `/api/saves` 文档保存 API
+- 读写 `SAVES_DIR` 指向的 JSON 文档目录
+- 静态托管 `dist/` 前端文件
+- 对非 `/api` 路径返回前端入口，支持刷新页面
+
+## 1Panel 部署建议
+
+推荐服务器目录：
+
+```text
+/opt/kotonoha
+```
+
+上传项目后执行：
+
+```bash
+cd /opt/kotonoha
+npm install
+npm run build
+mkdir -p /opt/kotonoha/data/saves
+```
+
+Node 应用配置：
+
+```text
+项目目录：/opt/kotonoha
+启动命令：npm run start
+端口：3002
+环境变量：
+  PORT=3002
+  HOST=0.0.0.0
+  SAVES_DIR=/opt/kotonoha/data/saves
+```
+
+OpenResty / 网站反向代理：
+
+```text
+/api/  -> http://127.0.0.1:3002
+/      -> http://127.0.0.1:3002
+```
+
+数据备份重点：
+
+```text
+/opt/kotonoha/data/saves
+```
+
+## Android App 打包
+
+本项目使用 Capacitor 生成 Android 工程。
+
+Android 测试包会读取 `.env.android`：
+
+```text
+VITE_API_BASE_URL=http://49.232.185.154:3002
+```
+
+如果以后换成域名和 HTTPS，改这里即可：
+
+```text
+VITE_API_BASE_URL=https://your-domain.com
+```
+
+生成/同步 Android 工程：
+
+```bash
+npm install
+npm run build:android
+npm run cap:sync
+npm run cap:open
+```
+
+然后在 Android Studio 里：
+
+```text
+Build -> Build Bundle(s) / APK(s) -> Build APK(s)
+```
+
+当前测试版使用 HTTP 访问服务器，`android/app/src/main/AndroidManifest.xml` 已开启：
+
+```text
+android:usesCleartextTraffic="true"
+```
+
+以后改成 HTTPS 后可以关闭这个配置。