zizi-al/new-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update remote deployment and upgrade notes

Browse Source
This commit is contained in:
zizi 2026-04-12 08:31:04 +08:00
parent dd0b85213b
commit 753cfa253a
5 changed files with 644 additions and 165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

219
AGENTS.md
View File

@ -138,7 +138,16 @@ For request structs that are parsed from client JSON and then re-marshaled to up
### 1. 部署与配置位置
- 远程服务器：`个人-minione-ubuntu-infra-4c16g120g`
- `new-api` 以 Docker 容器运行，容器名：`new-api`
- `new-api` 当前由宿主机 `systemd` 直接运行，不再以应用 Docker 容器运行。
- 当前部署目录：
- `/root/new-api-deploy`
- 当前关键文件：
- systemd 单元：`/etc/systemd/system/new-api.service`
- 运行环境：`/root/new-api-deploy/.env.runtime`
- 可执行文件：`/root/new-api-deploy/new-api`
- 当前共享基础设施入口：
- PostgreSQL：`127.0.0.1:5433`
- Redis：`127.0.0.1:6379`
- 渠道配置不在 `docker-compose.yml` 里维护，核心数据在 PostgreSQL 数据库表中：
- `channels`
- `abilities`
@ -199,7 +208,7 @@ For request structs that are parsed from client JSON and then re-marshaled to up
- 查问题时必须先看数据库 `options` 实际内容。
### 7. 线上热同步行为
- `new-api` 会定时从数据库同步 `options` 和 `channels`，不需要每次都重启容器。
- `new-api` 会定时从数据库同步 `options` 和 `channels`，不需要每次都重启服务。
- 日志关键字：
- `syncing options from database`
- `syncing channels from database`
@ -224,170 +233,50 @@ For request structs that are parsed from client JSON and then re-marshaled to up
- 是上游不通
- 还是服务端计费配置缺失
## 9. 当前线上部署形态（2026-04-04 更新）
- 远程服务器仍是：`个人-minione-ubuntu-infra-4c16g120g`
- `new-api` **不再**以 Docker 应用容器运行；当前由宿主机 `systemd` 服务启动：
- 服务名：`new-api`
- `systemctl is-active new-api` 应返回 `active`
- `systemctl is-enabled new-api` 应返回 `enabled`
- 当前线上运行版本固定为最新稳定 tag：
- `v0.11.9`
- 实际部署目录不是 `/root/new-api`，而是单独的源码 worktree：
- `/root/new-api-v0.11.9`
- 关键文件：
- 二进制：`/root/new-api-v0.11.9/new-api`
- 运行环境：`/root/new-api-v0.11.9/.env.runtime`
- 启动脚本：`/root/new-api-v0.11.9/run-new-api.sh`
- systemd 单元文件：`/etc/systemd/system/new-api.service`
## 9. 远程运行事实入口
- `AGENTS.md` 只保留项目规则、代码约束和少量排障结论。
- 具体远程部署、主机拓扑、端口、备份、Gitea 运行方式、镜像策略、方案 A Git 工作流，统一收口到：
- `ops/remote/README.md`
- `ops/remote/TEMPLATE.AGENT.md`
- `ops/remote/minione-ubuntu-infra-4c16g120g.AGENT.md`
- 后续如果远程运行事实再变，不要继续把细节堆回这里，直接更新 `ops/remote/` 下对应主机文档。
## 10. 依赖服务与连接方式（2026-04-04 更新）
- PostgreSQL 和 Redis 仍然跑在 Docker 中，但**只作为依赖容器**存在，不再承载应用本体。
- 当前容器：
- PostgreSQL：`postgres`
- Redis：`redis`
- 当前宿主机固定入口：
- PostgreSQL：`127.0.0.1:5433`
- Redis：`127.0.0.1:6379`
- `new-api` 宿主机进程必须连接宿主机固定入口，不要再依赖容器名或容器 IP：
- `SQL_DSN=postgresql://root:123456@127.0.0.1:5433/new-api`
- `REDIS_CONN_STRING=redis://127.0.0.1:6379`
- 原因：
- 容器 IP 会变，写死就是垃圾设计。
- 用宿主机固定入口，重建 PG/Redis 容器时不需要改应用配置。
## 10. 当前远程管理约定
- 当前 `infra` 主机的真实运行状态以 `ops/remote/minione-ubuntu-infra-4c16g120g.AGENT.md` 为准。
- 这份主机文档已经覆盖：
- `new-api` 的 systemd 源码部署
- `new-api` 的远程源码构建链（Go + Bun）
- `new-api-upgrade` 升级脚本
- Gitea 的 Docker Compose 部署
- PostgreSQL / Redis 的共享方式
- Gitea 访问 GitHub 的代理要求
- `admin/new-api` 镜像仓库
- `admin/new-api-dev` 可写开发仓库
- 本地仓库的方案 A 同步流程
- 新机器、新环境、新项目都按同样模式在 `ops/remote/` 下新增实例文档，不要再往项目根 `AGENTS.md` 追加主机级流水账。
## 11. 数据保护与备份（2026-04-04 更新）
- PostgreSQL 数据仍保存在 Docker volume：
- `new-api_pg_data`
- **不要**删除、重建、覆盖这个 volume，除非明确知道自己在做什么。
- 本次切换前已做 PG 备份：
- `/root/backups/new-api/new-api-cutover-20260404-094849.dump`
- 这次切换后已核对关键表仍在：
- `channels=10`
- `abilities=153`
- `options=9`
## 12. 运维入口与排障顺序（2026-04-04 更新）
- 现在排障先看 `systemd`，不是先看 Docker 应用容器：
## 11. 当前远程启动与升级约定（2026-04-12 更新）
- `new-api` 启动命令由 `systemd` 执行：
- `ExecStart=/root/new-api-deploy/new-api --port 3000 --log-dir /root/new-api-deploy/logs`
- 正常启动/重启入口：
- `systemctl restart new-api`
- `systemctl status new-api`
- `journalctl -u new-api -n 200 --no-pager`
- `journalctl -u new-api -f`
- 服务健康检查：
- `curl http://127.0.0.1:3000/api/status`
- 当前线上版本应看到：
- `v0.11.9`
- Docker 现在只需要关心依赖容器是否活着：
- `docker ps | grep -E 'postgres|redis'`
- 不要再默认使用 `/root/new-api/docker-compose.yml` 管理应用本体。
- 这个仓库目录现在主要是源码主仓库，不是实际运行目录。
- 实际运行目录是 `/root/new-api-v0.11.9`
## 13. 后续升级原则（2026-04-04 更新）
- 升级时优先选择新的**稳定 tag**，不要直接拿 `main` 或 `latest` 当生产版本。
- 合理流程应该是：
1. 为目标稳定 tag 建单独部署目录或 worktree
2. 编译产出新二进制
3. 保留 PG volume，不迁移数据库文件路径
4. 让 systemd 指向新版本
5. 验证 `api/status`、日志、数据库连接再收尾
- 如果有人再次看到 `docker-compose.yml` 里定义了 `new-api` 服务，不要想当然地认定线上还在用容器跑应用；先查：
- `systemctl status new-api`
- `ss -lntp | grep :3000`
## 14. infra 虚拟机上的 Gitea 部署（2026-04-04 更新）
- 远程服务器：`个人-minione-ubuntu-infra-4c16g120g`
- Gitea 当前以 Docker 方式部署，不与 `new-api` 共用应用容器。
- 当前镜像固定为稳定版本：
- `docker.gitea.com/gitea:1.25.5`
- 容器名：
- `gitea`
- 访问端口：
- Web：`3001`
- SSH：`2222`
- 当前 Web 根地址配置为：
- `http://100.64.0.11:3001/`
- 如果后续公网域名或访问地址变了，优先修改：
- `/opt/gitea/data/gitea/conf/app.ini`
- 重点字段：`DOMAIN`、`SSH_DOMAIN`、`ROOT_URL`
## 15. Gitea 数据与配置位置（2026-04-04 更新）
- Gitea 部署目录：
- `/opt/gitea`
- compose 文件：
- `/opt/gitea/docker-compose.yml`
- Gitea 数据目录（bind mount，不是 named volume）：
- `/opt/gitea/data`
- 主配置文件：
- `/opt/gitea/data/gitea/conf/app.ini`
- 敏感环境变量文件（root only）：
- `/opt/gitea/.env`
- 这份 `.env` 里包含：
- PostgreSQL 密码
- Gitea 管理员初始密码
- Gitea 各类 secret/jwt token
- 不要把 `/opt/gitea/.env` 提交到仓库、复制到公开位置或随手改权限。
## 16. Gitea 与 PostgreSQL 的关系（2026-04-04 更新）
- Gitea **复用了现有 PostgreSQL 实例**，但没有复用 `new-api` 的数据库。
- Gitea 专用 PostgreSQL 角色与数据库：
- role：`gitea`
- database：`gitea`
- 连接方式不是宿主机 `127.0.0.1:5433`，而是容器内直接走共享 Docker 网络：
- host：`postgres:5432`
- 共享网络：
- `new-api_new-api-network`
- 原则：
- 复用的是 PG 实例，不是 `new-api` 数据库。
- 不要把 Gitea 表写进 `new-api` 库，那是纯粹找死。
## 17. Gitea 运维与排障（2026-04-04 更新）
- 查看状态：
- `cd /opt/gitea && docker compose ps`
- `docker ps | grep gitea`
- 查看日志：
- `docker logs -f gitea`
- 重启：
- `cd /opt/gitea && docker compose restart`
- 健康检查：
- `curl --noproxy '*' http://127.0.0.1:3001/`
- 由于远程机器设置了代理环境变量，使用本机 `curl` 打本机端口时优先加：
- `--noproxy '*'`
- 否则很容易出现假的 `502`，把问题看错。
- Gitea SSH 应走**内置 SSH 服务**，当前正确的宿主机端口映射是：
- `2222:2222`
- 不要把宿主机 `2222` 映射到容器 `22`。
- 那样连到的是容器里的 OpenSSH，不是 Gitea SSH，用户公钥会“看起来加了但就是登不上”。
## 18. Gitea 初始化状态（2026-04-04 更新）
- 当前已完成初始化，不是安装向导状态。
- 首页应能看到：
- `Explore`
- `Sign In`
- 当前已创建管理员账号：
- 用户名：`admin`
- 初始密码不写进文档正文，去看：
- `/opt/gitea/.env`
- 第一次登录后应尽快修改管理员密码。
- 当前推荐通过 Tailscale 地址访问：
- Web：`http://100.64.0.11:3001/`
- SSH：`ssh -p 2222 git@100.64.0.11`
- 当前设备的 SSH 公钥已加入 `admin` 账号，key title 为：
- `qingse-macbook-id_ed25519`
- 如果后续再次修改了 `2222` 的目标服务，客户端可能需要刷新：
- `~/.ssh/known_hosts`
## 19. Gitea 上的 new-api 镜像仓库（2026-04-04 更新）
- 已在 Gitea 中创建仓库：
- `admin/new-api`
- 当前不是普通仓库，而是 **GitHub pull mirror**：
- 上游：`https://github.com/QuantumNous/new-api.git`
- Gitea 地址：`http://100.64.0.11:3001/admin/new-api`
- SSH clone：`ssh://git@100.64.0.11:2222/admin/new-api.git`
- 当前镜像同步间隔：
- `24h0m0s`
- 这类 mirror 的核心用途是同步 Git 数据：
- branches
- tags
- commits
- 不要把它误解成 GitHub 全量镜像站。
- 现在配置的不是 GitHub issue / PR / release 的持续双向同步。
- 它的重点是把仓库代码历史持续拉到 Gitea。
- 远程源码升级入口：
- `/usr/local/bin/new-api-upgrade`
- 这个脚本当前会执行：
1. `git fetch origin`
2. 切到 `home`
3. `git reset --hard origin/home`
4. `bun install`
5. `bun run build`
6. `go build`
7. `systemctl restart new-api`
8. 健康检查 `http://127.0.0.1:3000/api/status`
- 远程主机已补装源码构建工具链：
- `go`
- `bun`
- 关键注意事项：
- `new-api` 的前端产物 `web/dist` 是构建必需品，不能只跑 `go build`
- 当前仓库里的 `VERSION` 文件可能为空；升级脚本会回退到 Git 提交号作为版本字符串
- 远程部署 checkout 是 `/root/new-api-deploy`，不是旧的 `/root/new-api-v0.11.9`

363
ops/remote/GIT_GITEA.AGENT.md Normal file
View File

@ -0,0 +1,363 @@
# Git and Gitea Management AGENT
## Purpose
This document defines the canonical workflow for managing:
- local Git repositories
- GitHub upstream repositories
- writable Gitea repositories
- read-only Gitea mirror repositories
This file exists to prevent remote confusion, mirror misuse, and branch history corruption.
## 1. Core Principles
### 1.1 One repo, one role
Do not let a single remote repository play multiple conflicting roles.
A repository should be clearly one of:
- upstream source
- writable development remote
- read-only mirror
If a repository is a mirror, treat it as a mirror.
If a repository is writable, treat it as writable.
Do not mix the two.
### 1.2 Never confuse source of truth
The source of truth for official upstream code is the upstream repository, not the writable Gitea dev repo, and not the mirror.
### 1.3 Keep `main` clean
`main` is for syncing upstream only.
Do not pile local feature work directly into `main`.
### 1.4 Local changes belong on dev branches
Local work belongs on branches like:
- `home`
- `feature/*`
- `fix/*`
Do not treat the mirror repo as a development target.
## 2. Remote Roles
### 2.1 Canonical remote names
Use these exact names:
- `upstream` — official upstream source repository
- `gitea` — writable development repository on Gitea
Do not rename them casually.
### 2.2 Role definitions
#### `upstream`
Used only for:
- fetching latest official code
- comparing branch divergence
- updating local `main`
Example:
- `upstream -> https://github.com/QuantumNous/new-api.git`
#### `gitea`
Used only for:
- pushing local branches
- opening PRs on writable Gitea repos
- storing development work
Example:
- `gitea -> ssh://git@100.64.0.11:2222/admin/new-api-dev.git`
#### Read-only mirror repo
If a Gitea repo is configured as a pull mirror, it is read-only for development purposes.
Example:
- `admin/new-api` is a pull mirror of GitHub
- it is for sync / reference / backup
- it is not the target for normal pushes
Do not point `gitea` to a mirror repo.
## 3. Required Repository Topology
For projects that track an open-source upstream and also need private or self-hosted development:
- one upstream repo
- one writable Gitea dev repo
- optional one Gitea mirror repo
Recommended shape:
- `upstream` -> official GitHub repo
- `gitea` -> writable Gitea repo
- optional mirror repo exists separately but is not the main local push target
## 4. Branch Responsibilities
### `main`
Responsibilities:
- track upstream
- remain linear and clean
- only accept upstream sync commits or fast-forward updates
Rules:
- do not do feature development directly on `main`
- do not use `main` as a scratch branch
- prefer `merge --ff-only` when updating from upstream
### `home`
Responsibilities:
- personal development branch
- local operational or infrastructure work
- custom changes that do not belong on clean upstream `main`
Rules:
- rebase or merge onto updated `main`
- push to writable Gitea repo
- do not track upstream directly
### `feature/*`
Responsibilities:
- isolated work branches
- short-lived development branches
- branch off from current `main` or from `home` when appropriate
## 5. Standard Workflow
### 5.1 Inspect repository state
Always inspect first:
```bash
git remote -v
git branch -vv
git status --short
```
If remotes or tracking look wrong, fix them before pushing.
### 5.2 Sync local `main` with upstream
Preferred flow:
```bash
git fetch upstream
git switch main
git merge --ff-only upstream/main
git push gitea main
```
This keeps:
- local `main`
- writable Gitea `main`
aligned with upstream.
### 5.3 Update development branch after upstream sync
If using rebase:
```bash
git switch home
git rebase main
git push --force-with-lease gitea home
```
If using merge:
```bash
git switch home
git merge main
git push gitea home
```
Use `rebase` when clean linear history matters.
Use `merge` when you do not want history rewriting.
### 5.4 Create a new working branch
From updated `main`:
```bash
git switch main
git switch -c feature/<name>
```
Push it:
```bash
git push -u gitea feature/<name>
```
### 5.5 Push local changes
Always push to writable Gitea repo:
```bash
git push gitea <branch>
```
Do not push to mirror repos.
## 6. Fallback Workflow When GitHub Is Unreachable
If local machine cannot access GitHub, but the Gitea mirror is confirmed fresh, the mirror may be used as a temporary fetch source.
Example:
```bash
git fetch ssh://git@100.64.0.11:2222/admin/new-api.git refs/heads/main:refs/remotes/upstream/main
git switch main
git merge --ff-only upstream/main
git push gitea main
```
### Important restriction
Do this only after verifying that the mirror really matches upstream.
Check both sides:
- GitHub main commit
- Gitea mirror main commit
If they differ, do not use the mirror as a substitute for upstream.
## 7. Gitea Mirror Rules
If a Gitea repository is a pull mirror:
- it is a sync target, not a dev target
- pushes may fail or be meaningless
- it should be treated as read-only for development
Use mirror repos for:
- backup
- browsing
- clone acceleration
- temporary upstream fallback when verified fresh
Do not use mirror repos for:
- long-term feature branch work
- main development push target
- authoritative branch ownership
## 8. SSH Rules for Gitea
Use Gitea built-in SSH, not random container SSH assumptions.
Example working clone form:
```bash
git clone ssh://git@100.64.0.11:2222/admin/new-api-dev.git
```
If SSH suddenly breaks after a server-side SSH mapping change:
- verify host port mapping
- verify Gitea built-in SSH port
- refresh local `known_hosts` if host key changed
Example:
```bash
ssh-keygen -R '[100.64.0.11]:2222'
ssh -T -p 2222 git@100.64.0.11
```
## 9. Required Remote Configuration for This Project
Current expected shape:
- `upstream` -> official GitHub repository
- `gitea` -> writable Gitea development repository
Expected result style:
```text
gitea ssh://git@100.64.0.11:2222/admin/new-api-dev.git (fetch)
gitea ssh://git@100.64.0.11:2222/admin/new-api-dev.git (push)
upstream https://github.com/QuantumNous/new-api.git (fetch)
upstream https://github.com/QuantumNous/new-api.git (push)
```
Expected tracking style:
- `main` -> `upstream/main`
- `home` -> `gitea/home`
## 10. Forbidden Operations
Do not do the following unless you explicitly know why:
- push local feature work into a pull mirror repo
- remove `upstream` and pretend Gitea mirror is always equal to GitHub
- develop directly on `main`
- rewrite shared branch history without understanding the impact
- force-push `main`
- use mirror repos as the only source of upstream truth
- change remote roles casually
## 11. Minimal Recovery Rules
If repository roles become confused:
1. inspect remotes
2. identify which repo is writable and which is mirrored
3. restore:
- `upstream` -> official source
- `gitea` -> writable dev repo
4. restore tracking:
- `main` -> `upstream/main`
- dev branch -> `gitea/<branch>`
Useful commands:
```bash
git remote -v
git branch -vv
git config --get branch.main.remote
git config --get branch.main.merge
git config --get remote.pushDefault
```
## 12. Recommended Defaults
Set default push target to writable Gitea:
```bash
git config remote.pushDefault gitea
```
Set `main` tracking to upstream:
```bash
git branch --set-upstream-to=upstream/main main
```
Set dev branch tracking to Gitea:
```bash
git branch --set-upstream-to=gitea/home home
```
## 13. Human Rule
If you cannot explain, in one sentence, which remote is:
- official upstream
- writable dev remote
- mirror
then stop and fix the repository configuration before doing more Git work.

42
ops/remote/README.md Normal file
View File

@ -0,0 +1,42 @@
# Remote Deployment Inventory
This directory stores AGENT-style operational documents for remote hosts and deployed projects.
## Purpose
Use this directory to keep host-level deployment facts in one place so they do not get lost across shell history, chat logs, or ad hoc notes.
Keep these documents focused on runtime reality:
- where a service actually runs
- which port is really exposed
- where the real data lives
- which repo is writable versus mirrored
- how to inspect, restart, back up, and upgrade
## File Layout
- `TEMPLATE.AGENT.md` — reusable template for a new remote host or VM
- `<host>.AGENT.md` — filled document for a specific host
## Naming Convention
Use the stable host name in the file name when possible.
Examples:
- `minione-ubuntu-infra-4c16g120g.AGENT.md`
- `prod-k8s-edge-01.AGENT.md`
- `staging-gpu-node-02.AGENT.md`
## Suggested Update Rules
Update the host document whenever one of these changes:
- deployment mode changes, for example Docker to systemd
- runtime ports or hostnames change
- a new database, cache, or volume is introduced
- Git remotes or mirror strategy changes
- backup location or restore procedure changes
- a real incident reveals a hidden dependency or operational trap
## Current Hosts
- `minione-ubuntu-infra-4c16g120g.AGENT.md`

73
ops/remote/TEMPLATE.AGENT.md Normal file
View File

@ -0,0 +1,73 @@
# Remote Host AGENT Template
## 1. Host Identity
- Host name:
- Host role:
- Region or environment:
- Primary access path:
- Tailscale IP:
- Other important IPs or domains:
## 2. Access and Safety
- SSH profile or connection method:
- Primary operator:
- Privilege model:
- Proxy requirements:
- Secrets location:
- Important do-not-touch items:
## 3. Runtime Topology
- Main deployment styles on this host:
- Shared Docker networks:
- Shared databases or caches:
- Host-level ports in use:
- Reverse proxy or ingress layer:
## 4. Project Inventory
### Project: <name>
- Purpose:
- Deploy mode:
- Runtime entrypoint:
- Source repo path:
- Runtime directory:
- Main service or container names:
- Public or internal endpoints:
- Config files:
- Data location:
- Backup location:
- Logs and inspection commands:
- Upgrade path:
- Known traps:
## 5. Git and Repository Strategy
- Writable repositories:
- Mirror repositories:
- Upstream repositories:
- Default push targets:
- Branch strategy:
- Sync workflow:
## 6. Data and Backup
- Databases in use:
- Named volumes or bind mounts:
- Backup commands:
- Restore notes:
- High-risk destructive actions to avoid:
## 7. Routine Operations
- Check health:
- Check logs:
- Restart service:
- Restart containers:
- Verify ports:
- Verify external access:
## 8. Incident Notes
- Recent incidents:
- Root causes found:
- Permanent fixes applied:
- Remaining risks:
## 9. Change Log
- YYYY-MM-DD: <what changed>

112
ops/remote/minione-ubuntu-infra-4c16g120g.AGENT.md Normal file
View File

@ -0,0 +1,112 @@
# Remote Host AGENT — minione-ubuntu-infra-4c16g120g
## 1. Host Identity
- Host name: `minione-ubuntu-infra`
- Host role: personal infra VM for `new-api` and `gitea`
- Primary access path: Tabby SSH profile `个人-minione-ubuntu-infra-4c16g120g`
- Tailscale IP: `100.64.0.11`
- LAN IP: `192.168.1.3`
## 2. Runtime Topology
- `new-api` runs as a host `systemd` process
- `gitea` runs in Docker Compose under `/opt/gitea`
- PostgreSQL, Redis, Nginx run as shared Docker infrastructure
- Shared Docker network: `infra-shared`
## 3. Shared Infrastructure
### PostgreSQL
- Container: `infra-postgres`
- Host port: `127.0.0.1:5433`
- Docker alias: `infra-postgres:5432`
- Data path: `/srv/infra/postgres/data`
- Backup path: `/srv/infra/postgres/backup`
- Databases:
- `new-api`
- `gitea`
### Redis
- Container: `infra-redis`
- Host port: `127.0.0.1:6379`
- Docker alias: `infra-redis:6379`
- Data path: `/srv/infra/redis/data`
### Nginx
- Container: `infra-nginx`
- Host ports:
- `80`
- `443`
## 4. new-api
- Service name: `new-api`
- Deploy path: `/root/new-api-deploy`
- Runtime env: `/root/new-api-deploy/.env.runtime`
- Binary path: `/root/new-api-deploy/new-api`
- systemd unit: `/etc/systemd/system/new-api.service`
- Health check:
- `curl --noproxy '*' http://127.0.0.1:3000/api/status`
### Runtime Profile
- `SQL_DSN=postgresql://root:<password>@127.0.0.1:5433/new-api`
- `REDIS_CONN_STRING=redis://:<password>@127.0.0.1:6379/0`
### Source Build Toolchain
- `go version` -> currently `go1.25.1`
- `bun --version` -> currently `1.3.12`
- `node` / `npm` also exist, but frontend preferred tool is `bun`
### Source Upgrade Command
- `/usr/local/bin/new-api-upgrade`
This script currently does:
1. `git fetch origin`
2. `git switch home`
3. `git reset --hard origin/home`
4. `bun install`
5. `bun run build`
6. `go build`
7. `systemctl restart new-api`
8. health check against `127.0.0.1:3000`
### Important Notes
- `web/dist` is required for a valid backend build because `main.go` embeds it
- `VERSION` may be empty in the current branch; the upgrade script falls back to Git commit hash
- deployment checkout is branch-based now; do not go back to the old detached worktree deployment unless you explicitly mean to
## 5. gitea
- Compose path: `/opt/gitea/docker-compose.yml`
- Config path: `/opt/gitea/data/gitea/conf/app.ini`
- Web: `http://100.64.0.11:3001/`
- SSH: `ssh -p 2222 git@100.64.0.11`
- Database host: `infra-postgres:5432`
- Data path: `/opt/gitea/data`
## 6. Git and Repository Strategy
- Writable repo:
- `admin/new-api-dev`
- Mirror repo:
- `admin/new-api`
- Remote deploy checkout:
- `/root/new-api-deploy`
- Deploy branch:
- `home`
## 7. Routine Operations
- Check app health:
- `systemctl is-active new-api`
- `journalctl -u new-api -n 200 --no-pager`
- `curl --noproxy '*' http://127.0.0.1:3000/api/status`
- Run source upgrade:
- `/usr/local/bin/new-api-upgrade`
- Check infra:
- `docker ps --format '{{.Names}} | {{.Image}} | {{.Ports}}'`
- `ss -lntp | egrep ':3000|:3001|:2222|:5433|:6379|:80|:443'`
- Check gitea:
- `cd /opt/gitea && docker compose ps`
- `docker logs --tail 200 gitea`
- `curl --noproxy '*' http://127.0.0.1:3001/`
## 8. Current Reality Traps
- Do not treat `new-api/docker-compose.yml` as production truth; production app runtime is `systemd`
- Do not assume PostgreSQL belongs only to `new-api`; `gitea` shares the same PostgreSQL instance
- Do not assume remote host has no source-build capability anymore; Go and Bun are now installed