chore: initial sanitized public snapshot
This commit is contained in:
Aria2 Rust Pro Contributors
@@ -0,0 +1,188 @@
|
||||
# Migration Guide
|
||||
|
||||
This guide reflects the current active modernization state from
|
||||
`GOAL-modern.md` and `progress.md` for `aria2-rust-pro`. It is written for two
|
||||
existing audiences:
|
||||
|
||||
- users migrating from the [Aria2-Pro-Core](https://github.com/P3TERX/Aria2-Pro-Core)
|
||||
host binary
|
||||
- users running the current `Aria2-Pro-Docker` container shape
|
||||
|
||||
The short version is:
|
||||
|
||||
- aria2-style config syntax, session files, and RPC clients are intended to
|
||||
carry forward
|
||||
- the native host binary is now `aria2-rust-pro`, not a published
|
||||
`aria2-pro-core` drop-in tarball
|
||||
- the Docker image keeps the legacy env variable names and now maps the current
|
||||
Pro Docker knobs through the entrypoint/runtime config path
|
||||
|
||||
## Before You Cut Over
|
||||
|
||||
Make a copy of the three things that matter before any migration:
|
||||
|
||||
1. your current `aria2.conf`
|
||||
2. your `aria2.session` plus any adjacent `.aria2` control files
|
||||
3. the exact runtime command or compose file you use today
|
||||
|
||||
For Docker users, also record the current bind mounts or named volumes so that
|
||||
you know where `/config` and `/downloads` live on disk.
|
||||
|
||||
## Compatibility Snapshot
|
||||
|
||||
| Surface | Current `aria2-rust-pro` status | Migration meaning |
|
||||
| --- | --- | --- |
|
||||
| aria2-style config file | compatible target; current parser/runtime covers the common Pro/Core and Docker paths used here | keep your existing config and validate it with `--dry-run` before switching traffic |
|
||||
| Session and input files | current session persistence is implemented and covered by tests | keep existing session paths; do not delete `aria2.session` during cutover |
|
||||
| JSON-RPC and XML-RPC | current RPC surface is implemented enough for representative aria2 clients | reuse the same client URLs and tokens after you verify the new port and secret |
|
||||
| Native packaging | the public `v1.0.0` release is a source snapshot; local packaging commands produce host-specific artifacts | plan for a local Cargo build or your own packaged artifact |
|
||||
| Docker env names | the current Pro Docker env set is accepted and mapped by the entrypoint | keep the same env names, then verify the generated runtime config before cutover |
|
||||
|
||||
## From [Aria2-Pro-Core](https://github.com/P3TERX/Aria2-Pro-Core)
|
||||
|
||||
### What stays the same
|
||||
|
||||
- Keep your existing `aria2.conf` format.
|
||||
- Keep your current `aria2.session`.
|
||||
- Keep the Pro/Core option deltas that already exist in this rewrite, including
|
||||
the relaxed split and retry knobs tracked in the compatibility ledger.
|
||||
|
||||
### What changes
|
||||
|
||||
| Area | Old Core habit | `aria2-rust-pro` now |
|
||||
| --- | --- | --- |
|
||||
| Binary name | usually `aria2c` | native host binary is `aria2-rust-pro` |
|
||||
| Install flow | download a release tarball and move `aria2c` into place | build with Cargo or deploy your own packaged artifact |
|
||||
| RPC startup | config plus your old service wrapper | native startup still needs `--enable-rpc` on the command line to enter the long-running RPC server path |
|
||||
| Backgrounding | old wrappers often daemonized the process | do not rely on `--daemon` as a POSIX fork; supervise the foreground process with systemd, NSSM, Task Scheduler, or another service manager |
|
||||
|
||||
### Recommended host cutover
|
||||
|
||||
1. Build the new binary without overwriting the old one yet:
|
||||
|
||||
```powershell
|
||||
cargo build --release -p aria2-rust-pro-cli --bin aria2-rust-pro
|
||||
```
|
||||
|
||||
2. Stage a new config root and copy your current config/session into it.
|
||||
|
||||
3. Validate the config before swapping any service definition:
|
||||
|
||||
```powershell
|
||||
.\target\release\aria2-rust-pro.exe --dry-run --conf-path C:/ProgramData/aria2-rust-pro/aria2.conf
|
||||
```
|
||||
|
||||
4. Update your service or launcher to point at the new binary and keep
|
||||
`--enable-rpc` on the command line:
|
||||
|
||||
```powershell
|
||||
.\target\release\aria2-rust-pro.exe --conf-path C:/ProgramData/aria2-rust-pro/aria2.conf --enable-rpc
|
||||
```
|
||||
|
||||
5. Probe RPC before you disable the old service:
|
||||
|
||||
```powershell
|
||||
xh post http://127.0.0.1:6800/jsonrpc jsonrpc=2.0 id=migrate method=aria2.getVersion params:='["token:replace-with-a-strong-rpc-secret"]'
|
||||
```
|
||||
|
||||
If your surrounding scripts still hardcode `aria2c`, keep the old binary in
|
||||
place until you have either updated those scripts or installed your own wrapper
|
||||
or symlink that points `aria2c` to `aria2-rust-pro`.
|
||||
|
||||
## From `Aria2-Pro-Docker`
|
||||
|
||||
### What carries forward
|
||||
|
||||
- `/config/aria2.conf` remains the base config path.
|
||||
- `/config/aria2.session` remains the session file path.
|
||||
- `/downloads` remains the default download root.
|
||||
- the container still accepts the familiar Pro Docker env variable names
|
||||
|
||||
### What is different from the old Docker behavior
|
||||
|
||||
| Env or behavior | Old Pro Docker expectation | `aria2-rust-pro` now |
|
||||
| --- | --- | --- |
|
||||
| `RPC_SECRET` | old images often rewrote `aria2.conf` in place and could expose compatibility fallbacks | when set, it appends `rpc-secret` and `rpc-listen-all=true` into the generated runtime config; when empty, the entrypoint warns and keeps RPC loopback-only unless your base config overrides it |
|
||||
| `RPC_PORT` | runtime env + config rewrite | mapped into `/run/aria2-rust-pro/aria2.generated.conf` |
|
||||
| `LISTEN_PORT` | runtime env + config rewrite | mapped into generated config for both `listen-port` and `dht-listen-port` |
|
||||
| `DISK_CACHE` | runtime env + config rewrite | mapped into generated config |
|
||||
| `IPV6_MODE` | runtime env + config rewrite | mapped into generated config as `disable-ipv6=true/false` |
|
||||
| `UPDATE_TRACKERS` | functional startup/runtime knob | supported by the entrypoint; when enabled it runs the bundled tracker updater against the generated config |
|
||||
| `CUSTOM_TRACKER_URL` | functional tracker-updater input | supported by the entrypoint as the tracker updater source URL |
|
||||
| `SPECIAL_MODE` | functional mode hook | supported by the entrypoint for `move` and `rclone`; it copies default scripts and appends `on-download-complete=` to the generated config |
|
||||
| Config mutation | old image families often rewrote `/config/aria2.conf` directly | this image copies `/config/aria2.conf` only when missing, then writes overrides to `/run/aria2-rust-pro/aria2.generated.conf` |
|
||||
|
||||
### Recommended Docker staging flow
|
||||
|
||||
1. Stop the old container without deleting the existing `/config` and
|
||||
`/downloads` data.
|
||||
|
||||
2. Copy `docker/.env.example` to `docker/.env` and set your real values.
|
||||
|
||||
3. If your current data lives somewhere other than the compose defaults, adjust
|
||||
the volume paths in `docker/docker-compose.yml` before first start.
|
||||
|
||||
4. Build and start the replacement container:
|
||||
|
||||
```powershell
|
||||
docker compose --env-file docker/.env -f docker/docker-compose.yml up -d --build
|
||||
```
|
||||
|
||||
5. Confirm that the container preserved the base config and generated the
|
||||
runtime overlay:
|
||||
|
||||
```powershell
|
||||
docker exec aria2-rust-pro sh -lc "test -f /config/aria2.conf && sed 's/^rpc-secret=.*/rpc-secret=<redacted>/' /run/aria2-rust-pro/aria2.generated.conf"
|
||||
```
|
||||
|
||||
6. Probe RPC from the host:
|
||||
|
||||
```powershell
|
||||
xh post http://127.0.0.1:6800/jsonrpc jsonrpc=2.0 id=migrate method=aria2.getVersion params:='["token:replace-with-a-strong-rpc-secret"]'
|
||||
```
|
||||
|
||||
### Current Docker status
|
||||
|
||||
The Docker deployment lane is now materially real:
|
||||
|
||||
- `xtask docker smoke-local` verifies entrypoint/config generation without a
|
||||
daemon
|
||||
- `xtask docker smoke` builds the image, starts the container, verifies
|
||||
`aria2c --version`, checks the generated runtime config, and probes live
|
||||
JSON-RPC
|
||||
- `xtask docker export-local` can stage a portable image tar under
|
||||
`dist\docker\` when the daemon is reachable
|
||||
|
||||
The matching `scripts/docker/*.ps1` files remain thin compatibility wrappers
|
||||
for existing local workflows.
|
||||
|
||||
The entrypoint now:
|
||||
|
||||
- seeds a bundled `bt-tracker=` snapshot when the config leaves it empty
|
||||
- honors `UPDATE_TRACKERS` and `CUSTOM_TRACKER_URL` through the bundled tracker
|
||||
updater
|
||||
- honors `SPECIAL_MODE=move` and `SPECIAL_MODE=rclone` by materializing the
|
||||
matching hook scripts and appending `on-download-complete=...`
|
||||
|
||||
That makes the safe migration posture for existing Pro Docker users:
|
||||
|
||||
- stage the new image with the same `/config` and `/downloads` data
|
||||
- inspect `/run/aria2-rust-pro/aria2.generated.conf` after first boot
|
||||
- probe RPC before switching user traffic
|
||||
|
||||
Inside the container, `/usr/local/bin/aria2c` is a symlink to
|
||||
`/usr/local/bin/aria2-rust-pro`, so tools that `docker exec ... aria2c ...`
|
||||
still work after the image swap.
|
||||
|
||||
## Rollback
|
||||
|
||||
Keep rollback boring:
|
||||
|
||||
1. stop the new host service or container
|
||||
2. restore the old binary or old image reference
|
||||
3. put back the backed-up `aria2.conf` and `aria2.session`
|
||||
4. start the old deployment shape again
|
||||
|
||||
Rollback is much easier if you do not overwrite the old host binary path or
|
||||
delete the old Docker volumes until the RPC probe and a small real download
|
||||
both pass on the new deployment.
|
||||
Reference in New Issue
Block a user